0
# Transformers and Circuit Optimization
1

2
The transformers module provides tools for transforming and optimizing quantum circuits, including analytical decompositions, target gateset compilation, and circuit structure manipulation.
3

4
## Analytical Decompositions
5

6
### Single-Qubit Decompositions
7

8
```python { .api }
9
def single_qubit_matrix_to_gates(matrix: np.ndarray, tolerance: float = 1e-10) -> List['cirq.Operation']:
10
    """Decompose single-qubit unitary matrix into elementary gates.
11
    
12
    Args:
13
        matrix: 2x2 unitary matrix to decompose
14
        tolerance: Numerical tolerance for decomposition
15
        
16
    Returns:
17
        List of single-qubit operations implementing the matrix
18
    """
19

20
def single_qubit_matrix_to_pauli_rotations(matrix: np.ndarray, tolerance: float = 1e-10) -> List['cirq.Operation']:
21
    """Decompose single-qubit matrix into Pauli rotations."""
22

23
def single_qubit_matrix_to_phased_x_z(matrix: np.ndarray, tolerance: float = 1e-10) -> List['cirq.Operation']:
24
    """Decompose into phased X and Z rotations."""
25

26
def single_qubit_matrix_to_phxz(matrix: np.ndarray, tolerance: float = 1e-10) -> 'cirq.PhasedXZGate':
27
    """Decompose into single PhasedXZ gate."""
28

29
def single_qubit_op_to_framed_phase_form(op: 'cirq.Operation') -> List['cirq.Operation']:
30
    """Convert single-qubit operation to framed phase form."""
31
```
32

33
### Two-Qubit Decompositions
34

35
```python { .api }
36
def two_qubit_matrix_to_cz_operations(matrix: np.ndarray,
37
                                    qubits: Sequence['cirq.Qid'],
38
                                    tolerance: float = 1e-10) -> List['cirq.Operation']:
39
    """Decompose two-qubit unitary into CZ-based operations.
40
    
41
    Args:
42
        matrix: 4x4 unitary matrix
43
        qubits: Target qubits for decomposition
44
        tolerance: Numerical tolerance
45
        
46
    Returns:
47
        List of operations using single-qubit gates and CZ
48
    """
49

50
def two_qubit_matrix_to_sqrt_iswap_operations(
51
    q0: 'cirq.Qid',
52
    q1: 'cirq.Qid', 
53
    mat: np.ndarray,
54
    *,
55
    required_sqrt_iswap_count: int = None,
56
    use_sqrt_iswap_inv: bool = False,
57
    atol: float = 1e-8,
58
    check_preconditions: bool = True,
59
    clean_operations: bool = False,
60
) -> Sequence['cirq.Operation']:
61
    """Decompose two-qubit unitary into √iSWAP-based operations.
62
    
63
    Args:
64
        q0: First qubit
65
        q1: Second qubit  
66
        mat: 4x4 unitary matrix to decompose
67
        required_sqrt_iswap_count: Required number of √iSWAP gates (optional)
68
        use_sqrt_iswap_inv: Whether to use √iSWAP† gates
69
        atol: Absolute tolerance for decomposition
70
        check_preconditions: Whether to validate input matrix
71
        clean_operations: Whether to clean up negligible operations
72
        
73
    Returns:
74
        Sequence of operations implementing the matrix
75
    """
76

77
def two_qubit_matrix_to_ion_operations(matrix: np.ndarray,
78
                                     qubits: Sequence['cirq.Qid'],
79
                                     tolerance: float = 1e-10) -> List['cirq.Operation']:
80
    """Decompose for ion trap quantum computers using MS gates."""
81

82
def parameterized_2q_op_to_sqrt_iswap_operations(op: 'cirq.Operation',
83
                                               tolerance: float = 1e-10) -> List['cirq.Operation']:
84
    """Decompose parameterized two-qubit operation to √iSWAP gates."""
85
```
86

87
### Multi-Qubit Decompositions
88

89
```python { .api }
90
def three_qubit_matrix_to_operations(matrix: np.ndarray,
91
                                   qubits: Sequence['cirq.Qid'],
92
                                   tolerance: float = 1e-10) -> List['cirq.Operation']:
93
    """Decompose three-qubit unitary matrix.
94
    
95
    Args:
96
        matrix: 8x8 unitary matrix
97
        qubits: Target qubits
98
        tolerance: Numerical tolerance
99
        
100
    Returns:
101
        Decomposed operations
102
    """
103

104
def decompose_multi_controlled_x(qubits: Sequence['cirq.Qid'],
105
                               control_values: Sequence[int] = None,
106
                               work_qubits: Sequence['cirq.Qid'] = None) -> List['cirq.Operation']:
107
    """Decompose multi-controlled X gate."""
108

109
def decompose_multi_controlled_rotation(angles: Sequence[float],
110
                                      qubits: Sequence['cirq.Qid'],
111
                                      control_values: Sequence[int] = None) -> List['cirq.Operation']:
112
    """Decompose multi-controlled rotation gate."""
113
```
114

115
## Target Gatesets and Compilation
116

117
### Target Gateset Classes
118

119
```python { .api }
120
class CompilationTargetGateset:
121
    """Base class for target gatesets in compilation."""
122
    
123
    def __init__(self, *, name: str = None, 
124
                 unroll_circuit_op: bool = True) -> None:
125
        """Initialize compilation target gateset."""
126
        
127
    def decompose_to_target_gateset(self, op: 'cirq.Operation', 
128
                                  moment_index: int) -> 'cirq.OP_TREE':
129
        """Decompose operation to target gateset."""
130
        
131
    def preprocess_transformers(self) -> List['cirq.TRANSFORMER']:
132
        """Get preprocessing transformers."""
133
        
134
    def postprocess_transformers(self) -> List['cirq.TRANSFORMER']:
135
        """Get postprocessing transformers."""
136

137
class TwoQubitCompilationTargetGateset(CompilationTargetGateset):
138
    """Target gateset for two-qubit gate compilation."""
139
    
140
    def __init__(self, gate: 'cirq.Gate', **kwargs) -> None:
141
        """Initialize with specific two-qubit gate."""
142

143
class CZTargetGateset(TwoQubitCompilationTargetGateset):
144
    """Target gateset using CZ gates."""
145
    
146
    def __init__(self, *, atol: float = 1e-8, **kwargs) -> None:
147
        """Initialize CZ target gateset."""
148

149
class SqrtIswapTargetGateset(TwoQubitCompilationTargetGateset):
150
    """Target gateset using √iSWAP gates."""
151
    
152
    def __init__(self, *, atol: float = 1e-8, **kwargs) -> None:
153
        """Initialize √iSWAP target gateset."""
154
```
155

156
### Compilation Functions
157

158
```python { .api }
159
def optimize_for_target_gateset(circuit: 'cirq.Circuit',
160
                              gateset: CompilationTargetGateset,
161
                              context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
162
    """Optimize circuit for target gateset.
163
    
164
    Args:
165
        circuit: Input circuit to optimize
166
        gateset: Target gateset for compilation
167
        context: Transformation context
168
        
169
    Returns:
170
        Optimized circuit using only target gateset
171
    """
172

173
def create_transformer_with_kwargs(transformer: 'cirq.TRANSFORMER', **kwargs) -> 'cirq.TRANSFORMER':
174
    """Create transformer with additional keyword arguments."""
175
```
176

177
## Circuit Structure Transformations
178

179
### Alignment and Organization
180

181
```python { .api }
182
def align_left(circuit: 'cirq.Circuit', context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
183
    """Align circuit operations to the left (earliest possible moments).
184
    
185
    Args:
186
        circuit: Circuit to align
187
        context: Transformation context
188
        
189
    Returns:
190
        Left-aligned circuit
191
    """
192

193
def align_right(circuit: 'cirq.Circuit', context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
194
    """Align circuit operations to the right (latest possible moments)."""
195

196
def stratified_circuit(circuit: 'cirq.Circuit', 
197
                      categories: Sequence[Callable[['cirq.Operation'], bool]] = None,
198
                      context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
199
    """Create stratified circuit organizing operations by categories."""
200
```
201

202
### Moment Manipulation
203

204
```python { .api }
205
def drop_empty_moments(circuit: 'cirq.Circuit', context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
206
    """Remove empty moments from circuit.
207
    
208
    Args:
209
        circuit: Input circuit
210
        context: Transformation context
211
        
212
    Returns:
213
        Circuit with empty moments removed
214
    """
215

216
def merge_moments(circuit: 'cirq.Circuit', context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
217
    """Merge adjacent compatible moments."""
218

219
def drop_negligible_operations(circuit: 'cirq.Circuit',
220
                             atol: float = 1e-8,
221
                             context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
222
    """Remove operations with negligible effect."""
223

224
def is_negligible_turn(turn: Union[float, sympy.Expr], atol: float = 1e-8) -> bool:
225
    """Check if rotation angle is negligible."""
226
```
227

228
### Circuit Expansion and Composition
229

230
```python { .api }
231
def expand_composite(circuit: 'cirq.Circuit', context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
232
    """Expand composite operations in circuit.
233
    
234
    Args:
235
        circuit: Circuit with composite operations
236
        context: Transformation context
237
        
238
    Returns:
239
        Circuit with composite operations expanded
240
    """
241

242
def unroll_circuit_op(circuit: 'cirq.Circuit', 
243
                     context: 'cirq.TransformerContext' = None,
244
                     deep: bool = True,
245
                     tags_to_check: Sequence = ()) -> 'cirq.Circuit':
246
    """Unroll CircuitOperation instances in circuit."""
247

248
def unroll_circuit_op_greedy_earliest(circuit: 'cirq.Circuit',
249
                                     context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
250
    """Unroll circuit operations using greedy earliest strategy."""
251

252
def unroll_circuit_op_greedy_frontier(circuit: 'cirq.Circuit',
253
                                     context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
254
    """Unroll circuit operations using greedy frontier strategy."""
255
```
256

257
## Gate Merging and Optimization
258

259
### Single-Qubit Gate Merging
260

261
```python { .api }
262
def merge_single_qubit_gates_to_phased_x_and_z(circuit: 'cirq.Circuit',
263
                                              context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
264
    """Merge adjacent single-qubit gates into PhasedX and Z rotations.
265
    
266
    Args:
267
        circuit: Input circuit
268
        context: Transformation context
269
        
270
    Returns:
271
        Circuit with merged single-qubit gates
272
    """
273

274
def merge_single_qubit_gates_to_phxz(circuit: 'cirq.Circuit',
275
                                   context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
276
    """Merge single-qubit gates into PhasedXZ gates."""
277

278
def merge_single_qubit_moments_to_phxz(circuit: 'cirq.Circuit',
279
                                     context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
280
    """Merge single-qubit gates across moments into PhasedXZ."""
281

282
def merge_single_qubit_gates_to_phxz_symbolized(circuit: 'cirq.Circuit',
283
                                              context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
284
    """Symbolic merging of single-qubit gates."""
285
```
286

287
### Multi-Qubit Gate Merging
288

289
```python { .api }
290
def merge_k_qubit_unitaries(circuit: 'cirq.Circuit',
291
                          k: int = 2,
292
                          context: 'cirq.TransformerContext' = None,
293
                          merged_gate_tolerance: float = 1e-10) -> 'cirq.Circuit':
294
    """Merge adjacent k-qubit unitary operations.
295
    
296
    Args:
297
        circuit: Input circuit
298
        k: Number of qubits for unitary merging
299
        context: Transformation context
300
        merged_gate_tolerance: Tolerance for gate merging
301
        
302
    Returns:
303
        Circuit with merged k-qubit unitaries
304
    """
305

306
def merge_k_qubit_unitaries_to_circuit_op(circuit: 'cirq.Circuit',
307
                                         k: int = 2,
308
                                         context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
309
    """Merge k-qubit unitaries into CircuitOperations."""
310

311
def merge_operations(circuit: 'cirq.Circuit',
312
                   merge_func: Callable = None,
313
                   context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
314
    """Merge operations using custom merge function."""
315

316
def merge_operations_to_circuit_op(circuit: 'cirq.Circuit',
317
                                 merge_func: Callable = None,
318
                                 context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
319
    """Merge operations into CircuitOperations."""
320
```
321

322
## Measurement Transformations
323

324
### Measurement Manipulation
325

326
```python { .api }
327
def defer_measurements(circuit: 'cirq.Circuit', context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
328
    """Defer all measurements to the end of the circuit.
329
    
330
    Args:
331
        circuit: Circuit with measurements
332
        context: Transformation context
333
        
334
    Returns:
335
        Circuit with measurements moved to end
336
    """
337

338
def dephase_measurements(circuit: 'cirq.Circuit', context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
339
    """Add dephasing before measurements."""
340

341
def drop_terminal_measurements(circuit: 'cirq.Circuit', context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
342
    """Remove measurements at the end of circuit."""
343

344
def synchronize_terminal_measurements(circuit: 'cirq.Circuit',
345
                                    context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
346
    """Synchronize all terminal measurements to same moment."""
347
```
348

349
## Pauli Gate Transformations
350

351
### Pauli Ejection
352

353
```python { .api }
354
def eject_phased_paulis(circuit: 'cirq.Circuit', 
355
                       eject_parameterized: bool = False,
356
                       context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
357
    """Eject phased Pauli gates to the end of the circuit.
358
    
359
    Args:
360
        circuit: Input circuit
361
        eject_parameterized: Whether to eject parameterized Paulis
362
        context: Transformation context
363
        
364
    Returns:
365
        Circuit with Pauli gates ejected
366
    """
367

368
def eject_z(circuit: 'cirq.Circuit', 
369
           eject_parameterized: bool = False,
370
           context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
371
    """Eject Z gates to the end of circuit."""
372
```
373

374
## Transformer Framework
375

376
### Transformer Types and Context
377

378
```python { .api }
379
TRANSFORMER = Callable[['cirq.Circuit', 'cirq.TransformerContext'], 'cirq.Circuit']
380
"""Type for circuit transformer functions."""
381

382
def transformer(func: TRANSFORMER) -> TRANSFORMER:
383
    """Decorator to mark function as transformer."""
384

385
class TransformerContext:
386
    """Context for circuit transformations."""
387
    
388
    def __init__(self, *, logger: 'TransformerLogger' = None,
389
                 deep: bool = False,
390
                 tags_to_ignore: Sequence = ()) -> None:
391
        """Initialize transformer context."""
392
        
393
    @property
394
    def logger(self) -> 'TransformerLogger':
395
        """Logger for transformation steps."""
396
        
397
    def with_deep(self, deep: bool) -> 'TransformerContext':
398
        """Return context with different deep setting."""
399

400
class TransformerLogger:
401
    """Logger for circuit transformations."""
402
    
403
    def __init__(self, *, print_out: bool = True) -> None:
404
        """Initialize transformer logger."""
405
        
406
    def log(self, message: str, level: 'LogLevel' = 'LogLevel.INFO') -> None:
407
        """Log transformation message."""
408

409
class LogLevel(enum.Enum):
410
    """Logging levels for transformers."""
411
    DEBUG = 0
412
    INFO = 1 
413
    WARNING = 2
414
    ERROR = 3
415
```
416

417
## Primitive Operations
418

419
### Operation Mapping
420

421
```python { .api }
422
def map_moments(circuit: 'cirq.Circuit',
423
               map_func: Callable[['cirq.Moment', int], 'cirq.OP_TREE'],
424
               context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
425
    """Apply function to each moment in circuit.
426
    
427
    Args:
428
        circuit: Input circuit
429
        map_func: Function to apply to each moment
430
        context: Transformation context
431
        
432
    Returns:
433
        Transformed circuit
434
    """
435

436
def map_operations(circuit: 'cirq.Circuit',
437
                  map_func: Callable[['cirq.Operation', int], 'cirq.OP_TREE'],
438
                  context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
439
    """Apply function to each operation in circuit."""
440

441
def map_operations_and_unroll(circuit: 'cirq.Circuit',
442
                             map_func: Callable[['cirq.Operation', int], 'cirq.OP_TREE'],
443
                             context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit':
444
    """Map operations and unroll results."""
445
```
446

447
## Usage Examples
448

449
### Basic Circuit Transformations
450

451
```python
452
import cirq
453
import numpy as np
454

455
print("=== Circuit Alignment ===")
456
# Create circuit with operations that can be rearranged
457
qubits = cirq.LineQubit.range(3)
458
circuit = cirq.Circuit([
459
    cirq.X(qubits[0]),
460
    cirq.Y(qubits[1]),
461
    cirq.Z(qubits[2]),
462
    cirq.H(qubits[0]),
463
    cirq.CNOT(qubits[0], qubits[1])
464
])
465

466
print("Original circuit:")
467
print(circuit)
468

469
# Align left (earliest possible moments)
470
left_aligned = cirq.align_left(circuit)
471
print("\nLeft-aligned circuit:")
472
print(left_aligned)
473

474
# Align right (latest possible moments) 
475
right_aligned = cirq.align_right(circuit)
476
print("\nRight-aligned circuit:")
477
print(right_aligned)
478
```
479

480
### Single-Qubit Gate Optimization
481

482
```python
483
import cirq
484
import numpy as np
485

486
print("=== Single-Qubit Gate Merging ===")
487
# Create circuit with many single-qubit gates
488
qubit = cirq.LineQubit(0)
489
circuit = cirq.Circuit([
490
    cirq.H(qubit),
491
    cirq.X(qubit)**0.5,
492
    cirq.Z(qubit)**0.25,
493
    cirq.Y(qubit)**0.1,
494
    cirq.S(qubit)
495
])
496

497
print(f"Original circuit ({len(circuit)} moments):")
498
print(circuit)
499

500
# Merge into PhasedXZ gates
501
merged_circuit = cirq.merge_single_qubit_gates_to_phxz(circuit)
502
print(f"\nMerged circuit ({len(merged_circuit)} moments):")
503
print(merged_circuit)
504

505
# Verify circuits are equivalent
506
simulator = cirq.Simulator()
507
original_state = simulator.simulate(circuit).final_state_vector
508
merged_state = simulator.simulate(merged_circuit).final_state_vector
509
print(f"States equivalent: {np.allclose(original_state, merged_state)}")
510
```
511

512
### Target Gateset Compilation
513

514
```python
515
import cirq
516

517
print("=== Target Gateset Compilation ===")
518
# Create circuit with various two-qubit gates
519
qubits = cirq.LineQubit.range(2)
520
circuit = cirq.Circuit([
521
    cirq.H(qubits[0]),
522
    cirq.CNOT(qubits[0], qubits[1]),
523
    cirq.SWAP(qubits[0], qubits[1]),
524
    cirq.CZ(qubits[0], qubits[1])**0.5
525
])
526

527
print("Original circuit:")
528
print(circuit)
529

530
# Compile to CZ target gateset
531
cz_gateset = cirq.CZTargetGateset()
532
cz_circuit = cirq.optimize_for_target_gateset(circuit, cz_gateset)
533
print("\nCompiled to CZ gateset:")
534
print(cz_circuit)
535

536
# Compile to √iSWAP target gateset  
537
iswap_gateset = cirq.SqrtIswapTargetGateset()
538
iswap_circuit = cirq.optimize_for_target_gateset(circuit, iswap_gateset)
539
print("\nCompiled to √iSWAP gateset:")
540
print(iswap_circuit)
541
```
542

543
### Matrix Decomposition
544

545
```python
546
import cirq
547
import numpy as np
548

549
print("=== Matrix Decomposition ===")
550
# Create arbitrary two-qubit unitary
551
theta = np.pi / 3
552
phi = np.pi / 4
553
matrix = np.array([
554
    [np.cos(theta), -np.sin(theta), 0, 0],
555
    [np.sin(theta), np.cos(theta), 0, 0], 
556
    [0, 0, np.cos(phi), -np.sin(phi)],
557
    [0, 0, np.sin(phi), np.cos(phi)]
558
])
559

560
qubits = cirq.LineQubit.range(2)
561

562
# Decompose to CZ operations
563
cz_ops = cirq.two_qubit_matrix_to_cz_operations(matrix, qubits)
564
print(f"CZ decomposition ({len(cz_ops)} operations):")
565
for op in cz_ops:
566
    print(f"  {op}")
567

568
# Decompose to √iSWAP operations
569
iswap_ops = cirq.two_qubit_matrix_to_sqrt_iswap_operations(matrix, qubits)
570
print(f"\n√iSWAP decomposition ({len(iswap_ops)} operations):")
571
for op in iswap_ops:
572
    print(f"  {op}")
573

574
# Verify decomposition
575
circuit_cz = cirq.Circuit(cz_ops)
576
circuit_iswap = cirq.Circuit(iswap_ops)
577

578
print(f"\nCZ decomposition unitary matches: {np.allclose(matrix, cirq.unitary(circuit_cz))}")
579
print(f"√iSWAP decomposition unitary matches: {np.allclose(matrix, cirq.unitary(circuit_iswap))}")
580
```
581

582
### Measurement Transformations
583

584
```python
585
import cirq
586

587
print("=== Measurement Transformations ===")
588
# Create circuit with measurements throughout
589
qubits = cirq.LineQubit.range(3)
590
circuit = cirq.Circuit([
591
    cirq.H(qubits[0]),
592
    cirq.measure(qubits[0], key='early'),
593
    cirq.CNOT(qubits[0], qubits[1]),
594
    cirq.H(qubits[1]),
595
    cirq.measure(qubits[1], key='middle'),
596
    cirq.CNOT(qubits[1], qubits[2]),
597
    cirq.measure(qubits[2], key='late')
598
])
599

600
print("Original circuit:")
601
print(circuit)
602

603
# Defer measurements to end
604
deferred_circuit = cirq.defer_measurements(circuit)
605
print("\nDeferred measurements:")
606
print(deferred_circuit)
607

608
# Drop terminal measurements
609
no_measure_circuit = cirq.drop_terminal_measurements(deferred_circuit)
610
print("\nWithout terminal measurements:")
611
print(no_measure_circuit)
612
```
613

614
## Circuit Routing and Qubit Mapping
615

616
Transform logical circuits to physical hardware by mapping logical qubits to physical qubits and inserting SWAP operations as needed.
617

618
### Routing Algorithms
619

620
```python { .api }
621
class RouteCQC:
622
    """Route circuits using the Configurable Quantum Computer (CQC) routing algorithm."""
623
    def __init__(self, router_class: type, router_args: dict = None) -> None: ...
624
    def __call__(self, circuit: 'cirq.Circuit', device_graph: 'networkx.Graph') -> 'cirq.Circuit': ...
625

626
def routed_circuit_with_mapping(
627
    circuit: 'cirq.Circuit',
628
    device_graph: 'networkx.Graph',
629
    initial_mapper: 'AbstractInitialMapper' = None,
630
    router: 'RouteCQC' = None
631
) -> Tuple['cirq.Circuit', Dict['cirq.Qid', 'cirq.Qid']]:
632
    """Route a circuit and return both the routed circuit and the qubit mapping."""
633
```
634

635
### Initial Mapping Strategies
636

637
```python { .api }
638
class AbstractInitialMapper:
639
    """Abstract base for initial qubit mapping strategies."""
640
    def initial_mapping(self, circuit: 'cirq.Circuit', device_graph: 'networkx.Graph') -> Dict['cirq.Qid', 'cirq.Qid']: ...
641

642
class HardCodedInitialMapper(AbstractInitialMapper):
643
    """Use a pre-defined mapping between logical and physical qubits."""
644
    def __init__(self, initial_mapping: Dict['cirq.Qid', 'cirq.Qid']) -> None: ...
645

646
class LineInitialMapper(AbstractInitialMapper):
647
    """Map logical qubits to a line of physical qubits."""
648
```
649

650
### Mapping Management
651

652
```python { .api }
653
class MappingManager:
654
    """Manage the mapping between logical and physical qubits during routing."""
655
    def __init__(self, device_graph: 'networkx.Graph', initial_mapping: Dict['cirq.Qid', 'cirq.Qid'] = None) -> None: ...
656
    def current_mapping(self) -> Dict['cirq.Qid', 'cirq.Qid']: ...
657
    def apply_swap(self, swap_op: 'cirq.Operation') -> None: ...
658

659
def map_clean_and_borrowable_qubits(
660
    circuit: 'cirq.Circuit',
661
    qubit_map: Dict['cirq.Qid', 'cirq.Qid'],
662
    clean_qubits: Set['cirq.Qid'] = None,
663
    borrowable_qubits: Set['cirq.Qid'] = None
664
) -> 'cirq.Circuit':
665
    """Map qubits in a circuit, distinguishing between clean and borrowable ancilla qubits."""
666
```
667

668
## Gauge Compiling and Advanced Transformations
669

670
Advanced gauge-based transformations for two-qubit gate optimization and error mitigation.
671

672
### Gauge Framework
673

674
```python { .api }
675
class Gauge:
676
    """Abstract gauge transformation."""
677
    def weight(self) -> float: ...
678
    def sample(self, gate: 'cirq.Gate', prng: np.random.Generator) -> 'cirq.Gate': ...
679

680
class ConstantGauge(Gauge):
681
    """Gauge that always applies the same transformation."""
682
    def __init__(self, gauge_map: Dict['cirq.Gate', 'cirq.Gate']) -> None: ...
683

684
class GaugeSelector:
685
    """Select gauges based on various criteria."""
686
    def __init__(self, gauges: List[Gauge], selection_strategy: str = 'uniform') -> None: ...
687

688
class GaugeTransformer:
689
    """Apply gauge transformations to circuits."""
690
    def __init__(self, gauge_selector: GaugeSelector, num_gauge_selections: int = 1) -> None: ...
691
```
692

693
### Specialized Gauge Transformers
694

695
```python { .api }
696
class CZGaugeTransformer(GaugeTransformer):
697
    """Gauge transformer for CZ-based circuits."""
698

699
class ISWAPGaugeTransformer(GaugeTransformer):
700
    """Gauge transformer for iSWAP-based circuits."""
701

702
class SqrtCZGaugeTransformer(GaugeTransformer):
703
    """Gauge transformer for √CZ-based circuits."""
704

705
class SqrtISWAPGaugeTransformer(GaugeTransformer):
706
    """Gauge transformer for √iSWAP-based circuits."""
707

708
class SpinInversionGaugeTransformer(GaugeTransformer):
709
    """Apply spin inversion gauge transformations."""
710

711
class CPhaseGaugeTransformer(GaugeTransformer):
712
    """Gauge transformer for controlled-phase gates."""
713
```
714

715
## Noise and Error Mitigation Transformers
716

717
Advanced transformers for noise modeling and error mitigation techniques.
718

719
```python { .api }
720
class DepolarizingNoiseTransformer:
721
    """Add depolarizing noise to circuit operations."""
722
    def __init__(self, p_single: float = 0.001, p_two: float = 0.01) -> None: ...
723
    def __call__(self, circuit: 'cirq.Circuit', context: 'cirq.TransformerContext' = None) -> 'cirq.Circuit': ...
724

725
class RandomizedMeasurements:
726
    """Implement randomized measurement protocols for error mitigation."""
727
    def __init__(self, randomization_type: str = 'pauli') -> None: ...
728

729
def add_dynamical_decoupling(
730
    circuit: 'cirq.Circuit',
731
    decoupling_gates: List['cirq.Gate'] = None,
732
    insertion_strategy: str = 'periodic'
733
) -> 'cirq.Circuit':
734
    """Add dynamical decoupling sequences to idle periods in the circuit."""
735
```
736

737
## Tag and Symbol Transformers
738

739
Utilities for managing operation tags and symbolic parameters.
740

741
```python { .api }
742
def index_tags(circuit: 'cirq.Circuit', tag_class: type = None) -> 'cirq.Circuit':
743
    """Add index tags to operations for tracking and analysis."""
744

745
def remove_tags(circuit: 'cirq.Circuit', tag_classes: List[type] = None) -> 'cirq.Circuit':
746
    """Remove specified tags from all operations in the circuit."""
747

748
def toggle_tags(circuit: 'cirq.Circuit', tag_class: type, condition: Callable = None) -> 'cirq.Circuit':
749
    """Toggle tags on operations based on a condition function."""
750

751
class SymbolizeTag:
752
    """Tag for marking operations that should be symbolized."""
753

754
def symbolize_single_qubit_gates_by_indexed_tags(circuit: 'cirq.Circuit') -> 'cirq.Circuit':
755
    """Convert single-qubit gates with indexed tags to symbolic parameters."""
756
```
757

758
This comprehensive transformation framework enables circuit optimization, compilation to target hardware, routing for physical devices, advanced gauge transformations, noise modeling, and symbolic manipulation for improved performance and hardware compatibility.