0
# Gates and Operations
1
2
Qiskit provides a comprehensive library of quantum gates and operations, from basic Pauli gates to advanced multi-qubit operations and composite circuits. This library forms the foundation for quantum algorithm construction and circuit building.
3
4
## Capabilities
5
6
### Single-Qubit Gates
7
8
Fundamental single-qubit operations including Pauli gates, rotations, and Clifford gates.
9
10
```python { .api }
11
# Pauli Gates
12
class XGate(Gate):
13
def __init__(self, label=None):
14
"""Pauli-X gate (bit flip)."""
15
16
class YGate(Gate):
17
def __init__(self, label=None):
18
"""Pauli-Y gate."""
19
20
class ZGate(Gate):
21
def __init__(self, label=None):
22
"""Pauli-Z gate (phase flip)."""
23
24
class IGate(Gate):
25
def __init__(self, label=None):
26
"""Identity gate (no operation)."""
27
28
# Clifford Gates
29
class HGate(Gate):
30
def __init__(self, label=None):
31
"""Hadamard gate (X-Z basis rotation)."""
32
33
class SGate(Gate):
34
def __init__(self, label=None):
35
"""S gate (Z^(1/2) = sqrt(Z))."""
36
37
class SdgGate(Gate):
38
def __init__(self, label=None):
39
"""S-dagger gate (Z^(-1/2))."""
40
41
class TGate(Gate):
42
def __init__(self, label=None):
43
"""T gate (Z^(1/4))."""
44
45
class TdgGate(Gate):
46
def __init__(self, label=None):
47
"""T-dagger gate (Z^(-1/4))."""
48
49
class SXGate(Gate):
50
def __init__(self, label=None):
51
"""Square-root X gate (X^(1/2))."""
52
53
class SXdgGate(Gate):
54
def __init__(self, label=None):
55
"""Inverse square-root X gate (X^(-1/2))."""
56
57
# Rotation Gates
58
class RXGate(Gate):
59
def __init__(self, theta, label=None):
60
"""
61
Rotation about X-axis.
62
63
Parameters:
64
- theta: Rotation angle in radians
65
"""
66
67
class RYGate(Gate):
68
def __init__(self, theta, label=None):
69
"""
70
Rotation about Y-axis.
71
72
Parameters:
73
- theta: Rotation angle in radians
74
"""
75
76
class RZGate(Gate):
77
def __init__(self, phi, label=None):
78
"""
79
Rotation about Z-axis.
80
81
Parameters:
82
- phi: Rotation angle in radians
83
"""
84
85
class PhaseGate(Gate):
86
def __init__(self, theta, label=None):
87
"""
88
Phase gate with arbitrary phase.
89
90
Parameters:
91
- theta: Phase angle in radians
92
"""
93
94
class RGate(Gate):
95
def __init__(self, theta, phi, label=None):
96
"""
97
Single-qubit rotation about arbitrary axis.
98
99
Parameters:
100
- theta: Polar angle
101
- phi: Azimuthal angle
102
"""
103
104
# Universal Single-Qubit Gates
105
class UGate(Gate):
106
def __init__(self, theta, phi, lam, label=None):
107
"""
108
Generic single-qubit unitary gate.
109
110
Parameters:
111
- theta: Polar angle
112
- phi: Azimuthal angle
113
- lam: Phase angle
114
"""
115
116
class U1Gate(Gate):
117
def __init__(self, theta, label=None):
118
"""
119
Single-parameter U gate (phase only).
120
121
Parameters:
122
- theta: Phase angle
123
"""
124
125
class U2Gate(Gate):
126
def __init__(self, phi, lam, label=None):
127
"""
128
Two-parameter U gate.
129
130
Parameters:
131
- phi: First angle
132
- lam: Second angle
133
"""
134
135
class U3Gate(Gate):
136
def __init__(self, theta, phi, lam, label=None):
137
"""
138
Three-parameter U gate (most general single-qubit).
139
140
Parameters:
141
- theta: Polar angle
142
- phi: Azimuthal angle
143
- lam: Phase angle
144
"""
145
```
146
147
### Two-Qubit Gates
148
149
Essential two-qubit gates for entanglement and quantum correlations.
150
151
```python { .api }
152
# Controlled Gates
153
class CXGate(Gate):
154
def __init__(self, label=None, ctrl_state=None):
155
"""
156
Controlled-X gate (CNOT).
157
158
Parameters:
159
- ctrl_state: Control state (default: '1')
160
"""
161
162
class CYGate(Gate):
163
def __init__(self, label=None, ctrl_state=None):
164
"""Controlled-Y gate."""
165
166
class CZGate(Gate):
167
def __init__(self, label=None, ctrl_state=None):
168
"""Controlled-Z gate."""
169
170
class CHGate(Gate):
171
def __init__(self, label=None, ctrl_state=None):
172
"""Controlled-Hadamard gate."""
173
174
class CSGate(Gate):
175
def __init__(self, label=None, ctrl_state=None):
176
"""Controlled-S gate."""
177
178
class CSdgGate(Gate):
179
def __init__(self, label=None, ctrl_state=None):
180
"""Controlled-S-dagger gate."""
181
182
class CSXGate(Gate):
183
def __init__(self, label=None, ctrl_state=None):
184
"""Controlled-SX gate."""
185
186
class CPhaseGate(Gate):
187
def __init__(self, theta, label=None, ctrl_state=None):
188
"""
189
Controlled-phase gate.
190
191
Parameters:
192
- theta: Phase angle
193
"""
194
195
# Controlled Rotation Gates
196
class CRXGate(Gate):
197
def __init__(self, theta, label=None, ctrl_state=None):
198
"""
199
Controlled rotation about X-axis.
200
201
Parameters:
202
- theta: Rotation angle
203
"""
204
205
class CRYGate(Gate):
206
def __init__(self, theta, label=None, ctrl_state=None):
207
"""Controlled rotation about Y-axis."""
208
209
class CRZGate(Gate):
210
def __init__(self, theta, label=None, ctrl_state=None):
211
"""Controlled rotation about Z-axis."""
212
213
# Controlled U Gates
214
class CUGate(Gate):
215
def __init__(self, theta, phi, lam, gamma, label=None, ctrl_state=None):
216
"""
217
Controlled-U gate with global phase.
218
219
Parameters:
220
- theta, phi, lam: U gate parameters
221
- gamma: Global phase
222
"""
223
224
class CU1Gate(Gate):
225
def __init__(self, theta, label=None, ctrl_state=None):
226
"""Controlled-U1 gate."""
227
228
class CU3Gate(Gate):
229
def __init__(self, theta, phi, lam, label=None, ctrl_state=None):
230
"""Controlled-U3 gate."""
231
232
# Swap Gates
233
class SwapGate(Gate):
234
def __init__(self, label=None):
235
"""SWAP gate (exchange two qubits)."""
236
237
class iSwapGate(Gate):
238
def __init__(self, label=None):
239
"""Imaginary SWAP gate."""
240
241
# Specialized Two-Qubit Gates
242
class DCXGate(Gate):
243
def __init__(self, label=None):
244
"""Double-controlled X gate (equivalent to CNOT-CNOT)."""
245
246
class ECRGate(Gate):
247
def __init__(self, label=None):
248
"""Echoed cross-resonance gate."""
249
250
# Parameterized Two-Qubit Gates
251
class RXXGate(Gate):
252
def __init__(self, theta, label=None):
253
"""
254
Two-qubit XX rotation.
255
256
Parameters:
257
- theta: Rotation angle
258
"""
259
260
class RYYGate(Gate):
261
def __init__(self, theta, label=None):
262
"""Two-qubit YY rotation."""
263
264
class RZZGate(Gate):
265
def __init__(self, theta, label=None):
266
"""Two-qubit ZZ rotation."""
267
268
class RZXGate(Gate):
269
def __init__(self, theta, label=None):
270
"""Two-qubit ZX rotation."""
271
272
class XXMinusYYGate(Gate):
273
def __init__(self, theta, beta=0, label=None):
274
"""
275
XX-YY interaction gate.
276
277
Parameters:
278
- theta: Interaction strength
279
- beta: Single-qubit rotation angle
280
"""
281
282
class XXPlusYYGate(Gate):
283
def __init__(self, theta, beta=0, label=None):
284
"""XX+YY interaction gate."""
285
```
286
287
### Multi-Qubit Gates
288
289
Gates operating on three or more qubits including multi-controlled operations.
290
291
```python { .api }
292
# Multi-Controlled Gates
293
class CCXGate(Gate):
294
def __init__(self, label=None, ctrl_state=None):
295
"""
296
Toffoli gate (doubly-controlled X).
297
298
Parameters:
299
- ctrl_state: Control state for both controls
300
"""
301
302
class CCZGate(Gate):
303
def __init__(self, label=None):
304
"""Doubly-controlled Z gate."""
305
306
class CSwapGate(Gate):
307
def __init__(self, label=None):
308
"""Controlled SWAP gate (Fredkin gate)."""
309
310
class C3XGate(Gate):
311
def __init__(self, label=None, ctrl_state=None):
312
"""Triply-controlled X gate."""
313
314
class C3SXGate(Gate):
315
def __init__(self, label=None, ctrl_state=None):
316
"""Triply-controlled SX gate."""
317
318
class C4XGate(Gate):
319
def __init__(self, label=None, ctrl_state=None):
320
"""Quadruply-controlled X gate."""
321
322
class MCXGate(Gate):
323
def __init__(self, num_ctrl_qubits, label=None, ctrl_state=None, mode='noancilla'):
324
"""
325
Multi-controlled X gate.
326
327
Parameters:
328
- num_ctrl_qubits: Number of control qubits
329
- ctrl_state: Control state specification
330
- mode: Implementation mode ('noancilla', 'recursion', 'v-chain', etc.)
331
"""
332
333
class MCPhaseGate(Gate):
334
def __init__(self, lam, num_ctrl_qubits, label=None, ctrl_state=None):
335
"""
336
Multi-controlled phase gate.
337
338
Parameters:
339
- lam: Phase angle
340
- num_ctrl_qubits: Number of control qubits
341
"""
342
343
# Relative Phase Gates
344
class RCCXGate(Gate):
345
def __init__(self, label=None):
346
"""Relative-phase Toffoli gate (reduced CNOT count)."""
347
348
class RC3XGate(Gate):
349
def __init__(self, label=None):
350
"""Relative-phase triply-controlled X gate."""
351
352
# Global Phase
353
class GlobalPhaseGate(Gate):
354
def __init__(self, phase, label=None):
355
"""
356
Global phase gate.
357
358
Parameters:
359
- phase: Global phase angle
360
"""
361
```
362
363
### Generalized and Composite Gates
364
365
Advanced gates for complex quantum operations and algorithm building blocks.
366
367
```python { .api }
368
class UnitaryGate(Gate):
369
def __init__(self, data, label=None):
370
"""
371
Generic unitary gate from matrix.
372
373
Parameters:
374
- data: Unitary matrix (numpy array or Operator)
375
"""
376
377
class DiagonalGate(Gate):
378
def __init__(self, diag, label=None):
379
"""
380
Diagonal unitary gate.
381
382
Parameters:
383
- diag: Diagonal elements
384
"""
385
386
class PermutationGate(Gate):
387
def __init__(self, pattern, label=None):
388
"""
389
Permutation gate for qubit reordering.
390
391
Parameters:
392
- pattern: Permutation pattern
393
"""
394
395
class PauliGate(Gate):
396
def __init__(self, pauli_string, label=None):
397
"""
398
Multi-qubit Pauli gate.
399
400
Parameters:
401
- pauli_string: Pauli string (e.g., 'XYZИ')
402
"""
403
404
class LinearFunction(Gate):
405
def __init__(self, linear_matrix, validate_input=True):
406
"""
407
Linear function over GF(2).
408
409
Parameters:
410
- linear_matrix: Binary matrix defining linear function
411
- validate_input: Whether to validate matrix
412
"""
413
414
class Isometry(Gate):
415
def __init__(self, isometry, num_ancillas_zero, num_ancillas_dirty,
416
epsilon=1e-10, label=None):
417
"""
418
Isometry from smaller to larger Hilbert space.
419
420
Parameters:
421
- isometry: Isometry matrix
422
- num_ancillas_zero: Number of ancillas initialized to |0⟩
423
- num_ancillas_dirty: Number of dirty ancillas
424
- epsilon: Tolerance for optimization
425
"""
426
427
# Uniformly Controlled Gates
428
class UCGate(Gate):
429
def __init__(self, gate_list, up_to_diagonal=False, label=None):
430
"""
431
Uniformly controlled gate.
432
433
Parameters:
434
- gate_list: List of single-qubit gates
435
- up_to_diagonal: Whether decomposition is up to diagonal
436
"""
437
438
class UCPauliRotGate(UCGate):
439
def __init__(self, angle_list, rot_axis):
440
"""
441
Uniformly controlled Pauli rotations.
442
443
Parameters:
444
- angle_list: Rotation angles
445
- rot_axis: Rotation axis ('X', 'Y', or 'Z')
446
"""
447
448
class UCRXGate(UCPauliRotGate):
449
def __init__(self, angle_list):
450
"""Uniformly controlled RX rotations."""
451
452
class UCRYGate(UCPauliRotGate):
453
def __init__(self, angle_list):
454
"""Uniformly controlled RY rotations."""
455
456
class UCRZGate(UCPauliRotGate):
457
def __init__(self, angle_list):
458
"""Uniformly controlled RZ rotations."""
459
```
460
461
### Specialized Operations
462
463
Non-unitary operations and measurement-related instructions.
464
465
```python { .api }
466
class Measure(Instruction):
467
def __init__(self):
468
"""Quantum measurement operation."""
469
470
class Reset(Instruction):
471
def __init__(self):
472
"""Reset qubit to |0⟩ state."""
473
474
class Barrier(Instruction):
475
def __init__(self, num_qubits):
476
"""
477
Synchronization barrier.
478
479
Parameters:
480
- num_qubits: Number of qubits barrier acts on
481
"""
482
483
class Delay(Instruction):
484
def __init__(self, duration, unit='dt'):
485
"""
486
Time delay operation.
487
488
Parameters:
489
- duration: Delay duration
490
- unit: Time unit ('dt', 'ns', 'us', 'ms', 's')
491
"""
492
493
class Store(Instruction):
494
def __init__(self, lvalue):
495
"""
496
Store classical value.
497
498
Parameters:
499
- lvalue: Classical storage location
500
"""
501
```
502
503
### Gate Utilities and Functions
504
505
Helper functions for gate manipulation and circuit construction.
506
507
```python { .api }
508
def get_standard_gate_name_mapping():
509
"""
510
Get mapping from standard gate names to gate classes.
511
512
Returns:
513
Dict[str, Gate]: Mapping from names to gate classes
514
"""
515
516
def add_control(operation, num_ctrl_qubits=1, label=None, ctrl_state=None):
517
"""
518
Add control qubits to existing operation.
519
520
Parameters:
521
- operation: Gate or instruction to control
522
- num_ctrl_qubits: Number of control qubits to add
523
- label: Optional label
524
- ctrl_state: Control state specification
525
526
Returns:
527
ControlledGate: Controlled version of operation
528
"""
529
530
def power(operation, power, matrix_power=False):
531
"""
532
Raise gate to a power.
533
534
Parameters:
535
- operation: Gate to raise to power
536
- power: Exponent
537
- matrix_power: Whether to use matrix power
538
539
Returns:
540
Gate: Gate raised to power
541
"""
542
543
def inverse(operation):
544
"""
545
Get inverse of gate.
546
547
Parameters:
548
- operation: Gate to invert
549
550
Returns:
551
Gate: Inverse gate
552
"""
553
```
554
555
### Circuit Library
556
557
Qiskit's circuit library provides pre-built quantum circuits and algorithmic building blocks for common quantum computing patterns.
558
559
```python { .api }
560
from qiskit.circuit.library import *
561
562
# Standard gate library (already covered above)
563
# Available via: XGate, YGate, ZGate, HGate, etc.
564
565
# Arithmetic Circuits
566
class IntegerComparator:
567
def __init__(self, num_state_qubits, value, geq=True):
568
"""
569
Compare integer with a fixed value.
570
571
Parameters:
572
- num_state_qubits: Number of qubits representing the integer
573
- value: Value to compare against
574
- geq: True for >=, False for <
575
"""
576
577
class WeightedAdder:
578
def __init__(self, num_state_qubits, weights, mod=None):
579
"""
580
Add weighted sum to quantum register.
581
582
Parameters:
583
- num_state_qubits: Number of state qubits
584
- weights: List of weights for addition
585
- mod: Modulo for modular arithmetic (optional)
586
"""
587
588
class Multiplier:
589
def __init__(self, num_state_qubits, num_result_qubits):
590
"""
591
Quantum multiplier circuit.
592
593
Parameters:
594
- num_state_qubits: Number of qubits for each input
595
- num_result_qubits: Number of qubits for result
596
"""
597
598
# Boolean Logic Circuits
599
class AND:
600
def __init__(self, num_variable_qubits, flags=None):
601
"""
602
Multi-input AND gate.
603
604
Parameters:
605
- num_variable_qubits: Number of input qubits
606
- flags: List of flags for input inversion
607
"""
608
609
class OR:
610
def __init__(self, num_variable_qubits, flags=None):
611
"""
612
Multi-input OR gate.
613
614
Parameters:
615
- num_variable_qubits: Number of input qubits
616
- flags: List of flags for input inversion
617
"""
618
619
class XOR:
620
def __init__(self, num_qubits, amount=None):
621
"""
622
Multi-qubit XOR gate.
623
624
Parameters:
625
- num_qubits: Number of qubits
626
- amount: XOR amount (optional)
627
"""
628
629
# Data Encoding Circuits
630
class BasisEmbedding:
631
def __init__(self, feature_dimension, data_preparation=True):
632
"""
633
Encode classical data in computational basis states.
634
635
Parameters:
636
- feature_dimension: Number of features to encode
637
- data_preparation: Whether to add data preparation layer
638
"""
639
640
class AmplitudeEmbedding:
641
def __init__(self, num_qubits, normalize=False):
642
"""
643
Encode classical data in quantum amplitudes.
644
645
Parameters:
646
- num_qubits: Number of qubits
647
- normalize: Whether to normalize input data
648
"""
649
650
class AngleEmbedding:
651
def __init__(self, num_features, rotation='Y'):
652
"""
653
Encode features as rotation angles.
654
655
Parameters:
656
- num_features: Number of features
657
- rotation: Rotation gate ('X', 'Y', or 'Z')
658
"""
659
660
# N-Local Circuit Templates
661
class TwoLocal:
662
def __init__(self, num_qubits, rotation_blocks, entanglement_blocks, **kwargs):
663
"""
664
Two-local variational circuit.
665
666
Parameters:
667
- num_qubits: Number of qubits
668
- rotation_blocks: Single-qubit rotation gates
669
- entanglement_blocks: Two-qubit entangling gates
670
"""
671
672
class RealAmplitudes:
673
def __init__(self, num_qubits, reps=3):
674
"""
675
Real amplitudes ansatz (RY rotations + CX entanglement).
676
677
Parameters:
678
- num_qubits: Number of qubits
679
- reps: Number of repetitions
680
"""
681
682
class EfficientSU2:
683
def __init__(self, num_qubits, reps=3):
684
"""
685
Efficient SU(2) ansatz covering full SU(2) space.
686
687
Parameters:
688
- num_qubits: Number of qubits
689
- reps: Number of repetitions
690
"""
691
692
# Quantum Algorithm Primitives
693
class QFT:
694
def __init__(self, num_qubits, approximation_degree=0, do_swaps=True):
695
"""
696
Quantum Fourier Transform.
697
698
Parameters:
699
- num_qubits: Number of qubits
700
- approximation_degree: Degree of approximation (0 = exact)
701
- do_swaps: Whether to include bit-reversal swaps
702
"""
703
704
class GroverOperator:
705
def __init__(self, oracle, state_preparation=None, zero_reflection=None):
706
"""
707
Grover operator for amplitude amplification.
708
709
Parameters:
710
- oracle: Oracle circuit marking target states
711
- state_preparation: Initial state preparation
712
- zero_reflection: Zero state reflection operator
713
"""
714
715
class PhaseEstimation:
716
def __init__(self, num_evaluation_qubits, unitary):
717
"""
718
Quantum Phase Estimation algorithm.
719
720
Parameters:
721
- num_evaluation_qubits: Number of evaluation qubits
722
- unitary: Unitary operator for phase estimation
723
"""
724
725
# Quantum Volume and Benchmark Circuits
726
class QuantumVolume:
727
def __init__(self, num_qubits, depth=None, seed=None):
728
"""
729
Quantum Volume benchmark circuit.
730
731
Parameters:
732
- num_qubits: Number of qubits (must be square)
733
- depth: Circuit depth (equals num_qubits if None)
734
- seed: Random seed for reproducibility
735
"""
736
737
class Random:
738
def __init__(self, num_qubits, depth, max_operands=2, seed=None):
739
"""
740
Random quantum circuit.
741
742
Parameters:
743
- num_qubits: Number of qubits
744
- depth: Circuit depth
745
- max_operands: Maximum operands per gate
746
- seed: Random seed
747
"""
748
```
749
750
### Usage Examples
751
752
```python
753
from qiskit import QuantumCircuit
754
from qiskit.circuit.library import *
755
import numpy as np
756
757
# Basic single-qubit gates
758
circuit = QuantumCircuit(3)
759
circuit.h(0) # Hadamard
760
circuit.x(1) # Pauli-X
761
circuit.ry(np.pi/4, 2) # Y-rotation
762
763
# Two-qubit gates
764
circuit.cx(0, 1) # CNOT
765
circuit.cz(1, 2) # Controlled-Z
766
circuit.swap(0, 2) # SWAP
767
768
# Parameterized gates
769
theta = np.pi/3
770
circuit.rxx(theta, 0, 1) # XX rotation
771
circuit.ryy(theta/2, 1, 2) # YY rotation
772
773
# Multi-controlled gates
774
circuit.ccx(0, 1, 2) # Toffoli
775
circuit.mcx([0, 1, 2], 3) # 3-controlled X (needs 4 qubits)
776
777
# Advanced gates using gate classes directly
778
from qiskit.circuit.library import UnitaryGate, DiagonalGate
779
780
# Custom unitary from matrix
781
unitary_matrix = np.array([[1, 0], [0, np.exp(1j * np.pi/4)]])
782
custom_gate = UnitaryGate(unitary_matrix, label='CustomU')
783
circuit.append(custom_gate, [0])
784
785
# Diagonal gate
786
diag_elements = [1, -1, 1j, -1j] # 2-qubit diagonal
787
diag_gate = DiagonalGate(diag_elements)
788
circuit.append(diag_gate, [0, 1])
789
790
# Pauli string operations
791
pauli_gate = PauliGate('XYZ') # X⊗Y⊗Z on 3 qubits
792
circuit.append(pauli_gate, [0, 1, 2])
793
794
# Uniformly controlled rotations
795
angles = [0, np.pi/4, np.pi/2, 3*np.pi/4] # 4 angles for 2 control qubits
796
uc_ry = UCRYGate(angles)
797
circuit.append(uc_ry, [0, 1, 2]) # Controls: 0,1; Target: 2
798
799
# Gate power and control operations
800
from qiskit.circuit.library import add_control
801
802
# Square root of X gate
803
sqrt_x = SXGate()
804
circuit.append(sqrt_x, [0])
805
806
# Add control to any gate
807
controlled_ry = add_control(RYGate(np.pi/3), num_ctrl_qubits=2)
808
circuit.append(controlled_ry, [0, 1, 2]) # 2 controls, 1 target
809
810
# Gate composition and inverse
811
h_gate = HGate()
812
h_inverse = h_gate.inverse() # H† = H
813
circuit.append(h_inverse, [0])
814
815
# Measurement and reset
816
circuit.measure_all()
817
circuit.reset(0) # Reset first qubit
818
819
print(f"Circuit depth: {circuit.depth()}")
820
print(f"Gate counts: {circuit.count_ops()}")
821
```