0
# Quantum Operators
1

2
Construction of quantum operators including Pauli matrices, creation/annihilation operators, spin operators, and fundamental quantum mechanical operators.
3

4
## Capabilities
5

6
### Bosonic Operators
7

8
Creation, annihilation, and number operators for harmonic oscillator systems.
9

10
```python { .api }
11
def create(N: int, offset: int = 0) -> Qobj:
12
    """
13
    Create creation operator â†.
14
    
15
    Parameters:
16
    - N: Dimension of Hilbert space
17
    - offset: Lowest number state index
18
    
19
    Returns:
20
    - Qobj: Creation operator
21
    """
22

23
def destroy(N: int, offset: int = 0) -> Qobj:
24
    """
25
    Create annihilation operator â.
26
    
27
    Parameters:
28
    - N: Dimension of Hilbert space  
29
    - offset: Lowest number state index
30
    
31
    Returns:
32
    - Qobj: Annihilation operator
33
    """
34

35
def num(N: int, offset: int = 0) -> Qobj:
36
    """
37
    Create number operator â†â.
38
    
39
    Parameters:
40
    - N: Dimension of Hilbert space
41
    - offset: Lowest number state index
42
    
43
    Returns:
44
    - Qobj: Number operator
45
    """
46

47
def position(N: int, offset: int = 0) -> Qobj:
48
    """
49
    Create position operator x̂ = (↠+ â)/√2.
50
    
51
    Parameters:
52
    - N: Dimension of Hilbert space
53
    - offset: Lowest number state index
54
    
55
    Returns:
56
    - Qobj: Position operator
57
    """
58

59
def momentum(N: int, offset: int = 0) -> Qobj:
60
    """
61
    Create momentum operator p̂ = -i(↠- â)/√2.
62
    
63
    Parameters:
64
    - N: Dimension of Hilbert space
65
    - offset: Lowest number state index
66
    
67
    Returns:
68
    - Qobj: Momentum operator
69
    """
70
```
71

72
### Pauli Operators
73

74
Pauli matrices and related two-level system operators.
75

76
```python { .api }
77
def sigmax() -> Qobj:
78
    """
79
    Create Pauli-X (σₓ) operator.
80
    
81
    Returns:
82
    - Qobj: Pauli-X matrix [[0,1],[1,0]]
83
    """
84

85
def sigmay() -> Qobj:
86
    """
87
    Create Pauli-Y (σᵧ) operator.
88
    
89
    Returns:
90
    - Qobj: Pauli-Y matrix [[0,-i],[i,0]]
91
    """
92

93
def sigmaz() -> Qobj:
94
    """
95
    Create Pauli-Z (σᵤ) operator.
96
    
97
    Returns:
98
    - Qobj: Pauli-Z matrix [[1,0],[0,-1]]
99
    """
100

101
def sigmap() -> Qobj:
102
    """
103
    Create raising operator σ₊ = (σₓ + iσᵧ)/2.
104
    
105
    Returns:
106
    - Qobj: Raising operator [[0,1],[0,0]]
107
    """
108

109
def sigmam() -> Qobj:
110
    """
111
    Create lowering operator σ₋ = (σₓ - iσᵧ)/2.
112
    
113
    Returns:
114
    - Qobj: Lowering operator [[0,0],[1,0]]
115
    """
116
```
117

118
### Spin Operators
119

120
Angular momentum and spin operators for arbitrary spin values.
121

122
```python { .api }
123
def jmat(j: float, op: str = None) -> Qobj:
124
    """
125
    Create spin operator matrices.
126
    
127
    Parameters:
128
    - j: Spin quantum number (half-integer)
129
    - op: 'x', 'y', 'z', '+', '-' for specific component, None for all
130
    
131
    Returns:
132
    - Qobj or tuple: Single operator or tuple (Jₓ, Jᵧ, Jᵤ) for op=None
133
    """
134

135
def spin_Jx(j: float) -> Qobj:
136
    """
137
    Create x-component of spin operator.
138
    
139
    Parameters:
140
    - j: Spin quantum number
141
    
142
    Returns:
143
    - Qobj: Jₓ operator
144
    """
145

146
def spin_Jy(j: float) -> Qobj:
147
    """
148
    Create y-component of spin operator.
149
    
150
    Parameters:
151
    - j: Spin quantum number
152
    
153
    Returns:
154
    - Qobj: Jᵧ operator
155
    """
156

157
def spin_Jz(j: float) -> Qobj:
158
    """
159
    Create z-component of spin operator.
160
    
161
    Parameters:
162
    - j: Spin quantum number
163
    
164
    Returns:
165
    - Qobj: Jᵤ operator
166
    """
167

168
def spin_Jp(j: float) -> Qobj:
169
    """
170
    Create raising operator J₊.
171
    
172
    Parameters:
173
    - j: Spin quantum number
174
    
175
    Returns:
176
    - Qobj: J₊ operator
177
    """
178

179
def spin_Jm(j: float) -> Qobj:
180
    """
181
    Create lowering operator J₋.
182
    
183
    Parameters:
184
    - j: Spin quantum number
185
    
186
    Returns:
187
    - Qobj: J₋ operator
188
    """
189

190
def spin_J_set(j: float) -> tuple:
191
    """
192
    Create complete set of spin operators.
193
    
194
    Parameters:
195
    - j: Spin quantum number
196
    
197
    Returns:
198
    - tuple: (Jₓ, Jᵧ, Jᵤ) operators
199
    """
200
```
201

202
### Fermionic Operators
203

204
Creation and annihilation operators for fermionic systems.
205

206
```python { .api }
207
def fcreate(N: int, i: int = 0) -> Qobj:
208
    """
209
    Create fermionic creation operator with anti-commutation relations.
210
    
211
    Parameters:
212
    - N: Number of fermionic modes
213
    - i: Mode index (0 to N-1)
214
    
215
    Returns:
216
    - Qobj: Fermionic creation operator
217
    """
218

219
def fdestroy(N: int, i: int = 0) -> Qobj:
220
    """
221
    Create fermionic annihilation operator with anti-commutation relations.
222
    
223
    Parameters:
224
    - N: Number of fermionic modes  
225
    - i: Mode index (0 to N-1)
226
    
227
    Returns:
228
    - Qobj: Fermionic annihilation operator
229
    """
230
```
231

232
### Squeezing and Displacement Operators
233

234
Operators for continuous variable quantum optics.
235

236
```python { .api }
237
def squeeze(N: int, z: complex, offset: int = 0) -> Qobj:
238
    """
239
    Create single-mode squeezing operator S(z) = exp((z*↲ - z*â²)/2).
240
    
241
    Parameters:
242
    - N: Dimension of Hilbert space
243
    - z: Complex squeezing parameter
244
    - offset: Lowest number state index
245
    
246
    Returns:
247
    - Qobj: Squeezing operator
248
    """
249

250
def squeezing(a1: Qobj, a2: Qobj, z: complex) -> Qobj:
251
    """
252
    Create two-mode squeezing operator.
253
    
254
    Parameters:
255
    - a1: Annihilation operator for mode 1
256
    - a2: Annihilation operator for mode 2
257
    - z: Complex squeezing parameter
258
    
259
    Returns:
260
    - Qobj: Two-mode squeezing operator
261
    """
262

263
def displace(N: int, alpha: complex, offset: int = 0) -> Qobj:
264
    """
265
    Create displacement operator D(α) = exp(α↠- α*â).
266
    
267
    Parameters:
268
    - N: Dimension of Hilbert space
269
    - alpha: Complex displacement amplitude
270
    - offset: Lowest number state index
271
    
272
    Returns:
273
    - Qobj: Displacement operator
274
    """
275
```
276

277
### Utility Operators
278

279
Identity, zero, and other fundamental operators.
280

281
```python { .api }
282
def qeye(dimensions) -> Qobj:
283
    """
284
    Create identity operator.
285
    
286
    Parameters:
287
    - dimensions: Integer dimension or list of dimensions for tensor products
288
    
289
    Returns:
290
    - Qobj: Identity operator
291
    """
292

293
def identity(dimensions) -> Qobj:
294
    """
295
    Create identity operator (alias for qeye).
296
    
297
    Parameters:
298
    - dimensions: Integer dimension or list of dimensions
299
    
300
    Returns:
301
    - Qobj: Identity operator
302
    """
303

304
def qzero(dimensions) -> Qobj:
305
    """
306
    Create zero operator.
307
    
308
    Parameters:
309
    - dimensions: Integer dimension or list of dimensions
310
    
311
    Returns:
312
    - Qobj: Zero operator
313
    """
314

315
def qdiags(diagonals, offsets=None, dims=None, shape=None) -> Qobj:
316
    """
317
    Create diagonal operator from diagonal elements.
318
    
319
    Parameters:
320
    - diagonals: Array-like diagonal elements
321
    - offsets: Integer or list of diagonal offsets
322
    - dims: Dimensions for tensor structure
323
    - shape: Matrix shape
324
    
325
    Returns:
326
    - Qobj: Diagonal operator
327
    """
328

329
def commutator(A: Qobj, B: Qobj, kind: str = 'normal') -> Qobj:
330
    """
331
    Calculate commutator [A,B] = AB - BA or anti-commutator {A,B} = AB + BA.
332
    
333
    Parameters:
334
    - A: First operator
335
    - B: Second operator
336
    - kind: 'normal' for commutator, 'anti' for anti-commutator
337
    
338
    Returns:
339
    - Qobj: Commutator or anti-commutator
340
    """
341
```
342

343
### Specialized Operators
344

345
Phase, charge, tunneling, and other specialized quantum operators.
346

347
```python { .api }
348
def phase(N: int, phi0: float = 0) -> Qobj:
349
    """
350
    Create Pegg-Barnett phase operator.
351
    
352
    Parameters:
353
    - N: Dimension of Hilbert space
354
    - phi0: Reference phase
355
    
356
    Returns:
357
    - Qobj: Phase operator
358
    """
359

360
def charge(Nmax: int, Nmin: int = None, fock: bool = True) -> Qobj:
361
    """
362
    Create charge operator for superconducting circuits.
363
    
364
    Parameters:
365
    - Nmax: Maximum charge number
366
    - Nmin: Minimum charge number
367
    - fock: Use Fock basis if True
368
    
369
    Returns:
370
    - Qobj: Charge operator
371
    """
372

373
def tunneling(N: int, m: int = 1) -> Qobj:
374
    """
375
    Create tunneling operator between adjacent sites.
376
    
377
    Parameters:
378
    - N: Number of sites
379
    - m: Number of particles that tunnel
380
    
381
    Returns:
382
    - Qobj: Tunneling operator
383
    """
384

385
def qft(N: int, swap: bool = True) -> Qobj:
386
    """
387
    Create quantum Fourier transform operator.
388
    
389
    Parameters:
390
    - N: Dimension (must be power of 2 for qubit systems)
391
    - swap: Include bit-reversal swaps
392
    
393
    Returns:
394
    - Qobj: Quantum Fourier transform operator
395
    """
396

397
def swap(N: int = None, targets: list = [0, 1]) -> Qobj:
398
    """
399
    Create swap operator for exchanging two systems.
400
    
401
    Parameters:
402
    - N: Total number of qubits (if None, inferred from targets)
403
    - targets: List of two indices to swap
404
    
405
    Returns:
406
    - Qobj: Swap operator
407
    """
408
```
409

410
### Qutrit Operators
411

412
Operators for three-level quantum systems.
413

414
```python { .api }
415
def qutrit_ops() -> list:
416
    """
417
    Create set of qutrit operators (Gell-Mann matrices).
418
    
419
    Returns:
420
    - list: List of 8 qutrit operators (3×3 Gell-Mann matrices)
421
    """
422
```
423

424
### Usage Examples
425

426
```python
427
import qutip as qt
428
import numpy as np
429

430
# Harmonic oscillator operators
431
N = 10  # Truncated Hilbert space
432
a = qt.destroy(N)        # Annihilation operator
433
a_dag = qt.create(N)     # Creation operator  
434
n_op = qt.num(N)         # Number operator
435
x_op = qt.position(N)    # Position operator
436
p_op = qt.momentum(N)    # Momentum operator
437

438
# Verify canonical commutation relation [â,â†] = 1
439
comm = qt.commutator(a, a_dag)
440
print(comm)  # Should be identity
441

442
# Pauli operators for qubits
443
sx = qt.sigmax()  # σₓ
444
sy = qt.sigmay()  # σᵧ  
445
sz = qt.sigmaz()  # σᵤ
446
sp = qt.sigmap()  # σ₊
447
sm = qt.sigmam()  # σ₋
448

449
# Verify Pauli algebra: σₓσᵧ = iσᵤ
450
print(sx * sy - 1j * sz)  # Should be zero
451

452
# Spin-1/2 operators (same as Pauli/2)
453
Jx, Jy, Jz = qt.jmat(0.5)
454
print(2 * Jx == sx)  # True
455

456
# Spin-1 operators
457
J1x, J1y, J1z = qt.jmat(1.0)
458
print(J1x.shape)  # (3, 3) for spin-1
459

460
# Squeezing and displacement
461
z = 0.5           # Squeezing parameter
462
alpha = 1.0 + 0.5j  # Displacement amplitude
463
S = qt.squeeze(N, z)      # Squeezing operator
464
D = qt.displace(N, alpha) # Displacement operator
465

466
# Create squeezed coherent state
467
psi = D * S * qt.basis(N, 0)  # D(α)S(z)|0⟩
468

469
# Multi-mode operators
470
a1 = qt.tensor(qt.destroy(5), qt.qeye(5))  # Mode 1 in two-mode system
471
a2 = qt.tensor(qt.qeye(5), qt.destroy(5))  # Mode 2 in two-mode system
472

473
# Two-mode squeezing
474
S_two = qt.squeezing(a1, a2, 0.3)
475

476
# Fermionic operators for 3-mode system
477
c0_dag = qt.fcreate(3, 0)  # Create fermion in mode 0
478
c1 = qt.fdestroy(3, 1)     # Destroy fermion in mode 1
479

480
# Anti-commutation relation {cᵢ†,cⱼ} = δᵢⱼ
481
anticomm = qt.commutator(c0_dag, qt.fdestroy(3, 0), kind='anti')
482
print(anticomm)  # Should be identity
483

484
# Custom Hamiltonians
485
H_ho = 0.5 * p_op**2 + 0.5 * x_op**2  # Harmonic oscillator
486
H_qubit = 0.5 * sz                     # Two-level system
487
H_coupled = qt.tensor(sz, sz) + 0.1 * qt.tensor(sx, sx)  # Coupled qubits
488
```
489

490
## Types
491

492
```python { .api }
493
# All operator construction functions return Qobj instances with type='oper'
494
# representing quantum mechanical operators as matrices
495
```