or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

Files

docs

circuit-construction.mdcircuit-formats.mdgates-operations.mdindex.mdprimitives.mdproviders.mdquantum-information.mdsynthesis.mdtranspilation.mdvisualization.md

gates-operations.mddocs/

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

```