0
# Quantum State Construction
1

2
Creation of fundamental quantum states including basis states, coherent states, squeezed states, and multi-qubit entangled states.
3

4
## Capabilities
5

6
### Basic Quantum States
7

8
Fundamental quantum states for various physical systems.
9

10
```python { .api }
11
def basis(N: int, n: int = 0, offset: int = 0) -> Qobj:
12
    """
13
    Create basis state |n⟩ in N-dimensional Hilbert space.
14
    
15
    Parameters:
16
    - N: Dimension of Hilbert space
17
    - n: Index of basis state (0 to N-1)
18
    - offset: Lowest number state index
19
    
20
    Returns:
21
    - Qobj: Basis state |n⟩
22
    """
23

24
def fock(N: int, n: int = 0, offset: int = 0) -> Qobj:
25
    """
26
    Create Fock state |n⟩ (alias for basis).
27
    
28
    Parameters:
29
    - N: Dimension of Hilbert space
30
    - n: Photon/particle number
31
    - offset: Lowest number state index
32
    
33
    Returns:
34
    - Qobj: Fock state |n⟩
35
    """
36

37
def fock_dm(N: int, n: int = 0, offset: int = 0) -> Qobj:
38
    """
39
    Create Fock state density matrix |n⟩⟨n|.
40
    
41
    Parameters:
42
    - N: Dimension of Hilbert space
43
    - n: Photon/particle number
44
    - offset: Lowest number state index
45
    
46
    Returns:
47
    - Qobj: Fock state density matrix
48
    """
49

50
def qutrit_basis() -> list:
51
    """
52
    Create set of qutrit basis states {|0⟩, |1⟩, |2⟩}.
53
    
54
    Returns:
55
    - list: List of three qutrit basis states
56
    """
57

58
def zero_ket(N: int, dims: list = None) -> Qobj:
59
    """
60
    Create zero ket state |0⟩.
61
    
62
    Parameters:
63
    - N: Dimension of Hilbert space
64
    - dims: Dimensions for tensor structure
65
    
66
    Returns:
67
    - Qobj: Zero state |0⟩
68
    """
69
```
70

71
### Coherent and Continuous Variable States
72

73
States for continuous variable quantum systems and quantum optics.
74

75
```python { .api }
76
def coherent(N: int, alpha: complex, offset: int = 0, method: str = 'operator') -> Qobj:
77
    """
78
    Create coherent state |α⟩.
79
    
80
    Parameters:
81
    - N: Dimension of Hilbert space truncation
82
    - alpha: Complex coherent state amplitude
83
    - offset: Lowest number state index
84
    - method: 'operator' or 'analytic' calculation method
85
    
86
    Returns:
87
    - Qobj: Coherent state |α⟩
88
    """
89

90
def coherent_dm(N: int, alpha: complex, offset: int = 0, method: str = 'operator') -> Qobj:
91
    """
92
    Create coherent state density matrix |α⟩⟨α|.
93
    
94
    Parameters:
95
    - N: Dimension of Hilbert space truncation
96
    - alpha: Complex coherent state amplitude
97
    - offset: Lowest number state index
98
    - method: 'operator' or 'analytic' calculation method
99
    
100
    Returns:
101
    - Qobj: Coherent state density matrix
102
    """
103

104
def squeezed(N: int, z: complex, offset: int = 0, method: str = 'operator') -> Qobj:
105
    """
106
    Create squeezed vacuum state.
107
    
108
    Parameters:
109
    - N: Dimension of Hilbert space truncation
110
    - z: Complex squeezing parameter
111
    - offset: Lowest number state index
112
    - method: 'operator' or 'analytic' calculation method
113
    
114
    Returns:
115
    - Qobj: Squeezed vacuum state
116
    """
117

118
def displaced_fock(N: int, n: int, alpha: complex, offset: int = 0) -> Qobj:
119
    """
120
    Create displaced Fock state D(α)|n⟩.
121
    
122
    Parameters:
123
    - N: Dimension of Hilbert space truncation
124
    - n: Initial Fock state number
125
    - alpha: Displacement amplitude
126
    - offset: Lowest number state index
127
    
128
    Returns:
129
    - Qobj: Displaced Fock state
130
    """
131
```
132

133
### Thermal and Mixed States
134

135
Thermal equilibrium states and mixed quantum states.
136

137
```python { .api }
138
def thermal_dm(N: int, n: float, method: str = 'operator') -> Qobj:
139
    """
140
    Create thermal state density matrix.
141
    
142
    Parameters:
143
    - N: Dimension of Hilbert space truncation
144
    - n: Average thermal photon number
145
    - method: 'operator' or 'analytic' calculation method
146
    
147
    Returns:
148
    - Qobj: Thermal state density matrix
149
    """
150

151
def maximally_mixed_dm(N: int, dims: list = None) -> Qobj:
152
    """
153
    Create maximally mixed state ρ = I/N.
154
    
155
    Parameters:
156
    - N: Dimension of Hilbert space
157
    - dims: Dimensions for tensor structure
158
    
159
    Returns:
160
    - Qobj: Maximally mixed density matrix
161
    """
162

163
def ket2dm(state: Qobj) -> Qobj:
164
    """
165
    Convert ket state to density matrix |ψ⟩⟨ψ|.
166
    
167
    Parameters:
168
    - state: Input ket state
169
    
170
    Returns:
171
    - Qobj: Density matrix representation
172
    """
173
```
174

175
### Spin and Angular Momentum States
176

177
States for spin systems and angular momentum representations.
178

179
```python { .api }
180
def spin_state(j: float, m: float, type: str = 'ket') -> Qobj:
181
    """
182
    Create spin state |j,m⟩.
183
    
184
    Parameters:
185
    - j: Total angular momentum quantum number
186
    - m: Magnetic quantum number (-j ≤ m ≤ j)
187
    - type: 'ket' for state vector, 'dm' for density matrix
188
    
189
    Returns:
190
    - Qobj: Spin state |j,m⟩ or density matrix
191
    """
192

193
def spin_coherent(j: float, theta: float, phi: float, type: str = 'ket') -> Qobj:
194
    """
195
    Create spin coherent state.
196
    
197
    Parameters:
198
    - j: Spin quantum number
199
    - theta: Polar angle (0 to π)
200
    - phi: Azimuthal angle (0 to 2π)
201
    - type: 'ket' for state vector, 'dm' for density matrix
202
    
203
    Returns:
204
    - Qobj: Spin coherent state
205
    """
206
```
207

208
### Multi-qubit and Entangled States
209

210
Entangled states for quantum information and quantum computing applications.
211

212
```python { .api }
213
def bell_state(state: str = '00') -> Qobj:
214
    """
215
    Create Bell state.
216
    
217
    Parameters:
218
    - state: '00', '01', '10', or '11' for different Bell states
219
    
220
    Returns:
221
    - Qobj: Bell state (|00⟩±|11⟩)/√2 or (|01⟩±|10⟩)/√2
222
    """
223

224
def singlet_state() -> Qobj:
225
    """
226
    Create singlet state (|01⟩-|10⟩)/√2.
227
    
228
    Returns:
229
    - Qobj: Singlet state
230
    """
231

232
def triplet_states() -> list:
233
    """
234
    Create triplet states |T₁⟩, |T₀⟩, |T₋₁⟩.
235
    
236
    Returns:
237
    - list: List of three triplet state Qobj's
238
    """
239

240
def ghz_state(N: int = 3) -> Qobj:
241
    """
242
    Create N-qubit GHZ state (|00...0⟩+|11...1⟩)/√2.
243
    
244
    Parameters:
245
    - N: Number of qubits
246
    
247
    Returns:
248
    - Qobj: N-qubit GHZ state
249
    """
250

251
def w_state(N: int = 3) -> Qobj:
252
    """
253
    Create N-qubit W state (|100...0⟩+|010...0⟩+...+|00...01⟩)/√N.
254
    
255
    Parameters:
256
    - N: Number of qubits
257
    
258
    Returns:
259
    - Qobj: N-qubit W state
260
    """
261
```
262

263
### Computational Basis States
264

265
States for quantum computing in computational basis.
266

267
```python { .api }
268
def qstate(string: str, targets: list = None) -> Qobj:
269
    """
270
    Create multi-qubit computational basis state from string.
271
    
272
    Parameters:
273
    - string: Binary string like '0101' or '++--' for Pauli eigenstates
274
    - targets: List of target qubit indices
275
    
276
    Returns:
277
    - Qobj: Multi-qubit computational basis state
278
    """
279

280
def ket(string: str, dim: int = 2) -> Qobj:
281
    """
282
    Create ket state from string representation.
283
    
284
    Parameters:
285
    - string: String representation of quantum state
286
    - dim: Dimension per subsystem
287
    
288
    Returns:
289
    - Qobj: Ket state vector
290
    """
291

292
def bra(string: str, dim: int = 2) -> Qobj:
293
    """
294
    Create bra state from string representation.
295
    
296
    Parameters:
297
    - string: String representation of quantum state  
298
    - dim: Dimension per subsystem
299
    
300
    Returns:
301
    - Qobj: Bra state vector
302
    """
303
```
304

305
### State Indexing and Enumeration
306

307
Utilities for working with multi-level system state indexing.
308

309
```python { .api }
310
def state_number_enumerate(dims: list) -> list:
311
    """
312
    Enumerate all possible state configurations for composite system.
313
    
314
    Parameters:
315
    - dims: List of dimensions for each subsystem
316
    
317
    Returns:
318
    - list: All possible state number combinations
319
    """
320

321
def state_number_index(dims: list, state: list) -> int:
322
    """
323
    Convert state number list to single index.
324
    
325
    Parameters:
326
    - dims: List of dimensions for each subsystem
327
    - state: List of state numbers for each subsystem
328
    
329
    Returns:
330
    - int: Single index representing the state
331
    """
332

333
def state_index_number(dims: list, index: int) -> list:
334
    """
335
    Convert single index to state number list.
336
    
337
    Parameters:
338
    - dims: List of dimensions for each subsystem
339
    - index: Single index representing the state
340
    
341
    Returns:
342
    - list: List of state numbers for each subsystem
343
    """
344

345
def state_number_qobj(dims: list, state: list) -> Qobj:
346
    """
347
    Create basis state from state number list.
348
    
349
    Parameters:
350
    - dims: List of dimensions for each subsystem
351
    - state: List of state numbers for each subsystem
352
    
353
    Returns:
354
    - Qobj: Basis state corresponding to state numbers
355
    """
356
```
357

358
### Phase and Position States
359

360
Specialized states for continuous variable and phase space representations.
361

362
```python { .api }
363
def phase_basis(N: int, m: int, phi0: float = 0) -> Qobj:
364
    """
365
    Create Pegg-Barnett phase eigenstate.
366
    
367
    Parameters:
368
    - N: Dimension of Hilbert space
369
    - m: Phase state index
370
    - phi0: Reference phase
371
    
372
    Returns:
373
    - Qobj: Phase eigenstate
374
    """
375
```
376

377
### Projection Operators
378

379
States and projectors for measurement and quantum operations.
380

381
```python { .api }
382
def projection(N: int, n: int, offset: int = 0) -> Qobj:
383
    """
384
    Create projection operator |n⟩⟨n|.
385
    
386
    Parameters:
387
    - N: Dimension of Hilbert space
388
    - n: Index of basis state
389
    - offset: Lowest number state index
390
    
391
    Returns:
392
    - Qobj: Projection operator
393
    """
394
```
395

396
### Usage Examples
397

398
```python
399
import qutip as qt
400
import numpy as np
401

402
# Basic states
403
ground = qt.basis(2, 0)  # |0⟩ ground state
404
excited = qt.basis(2, 1)  # |1⟩ excited state
405
superpos = (ground + excited).unit()  # (|0⟩+|1⟩)/√2
406

407
# Harmonic oscillator states
408
vacuum = qt.fock(10, 0)      # |0⟩ vacuum state
409
n1_state = qt.fock(10, 1)    # |1⟩ single photon
410
thermal = qt.thermal_dm(10, 0.5)  # Thermal state with ⟨n⟩=0.5
411

412
# Coherent states
413
alpha = 1.0 + 0.5j
414
coh_state = qt.coherent(20, alpha)    # Coherent state |α⟩
415
coh_dm = qt.coherent_dm(20, alpha)    # Coherent density matrix
416

417
# Squeezed states
418
squeeze_param = 0.5
419
squeezed = qt.squeezed(20, squeeze_param)
420

421
# Multi-qubit entangled states
422
bell = qt.bell_state('00')    # |Φ⁺⟩ = (|00⟩+|11⟩)/√2
423
ghz3 = qt.ghz_state(3)        # 3-qubit GHZ state
424
w3 = qt.w_state(3)            # 3-qubit W state
425

426
# Spin states
427
j_half_up = qt.spin_state(0.5, 0.5)    # |1/2, 1/2⟩ spin-up
428
j_half_down = qt.spin_state(0.5, -0.5)  # |1/2, -1/2⟩ spin-down
429

430
# Spin coherent state pointing along (θ,φ)
431
theta, phi = np.pi/4, np.pi/3
432
spin_coh = qt.spin_coherent(0.5, theta, phi)
433

434
# Computational basis states from strings
435
three_qubit = qt.qstate('101')  # |101⟩ computational basis
436
pauli_eigen = qt.qstate('+-+')  # Pauli eigenstate
437

438
# Mixed states
439
mixed = qt.maximally_mixed_dm(4)  # Maximally mixed 4-level system
440

441
# Custom superposition
442
psi = 0.6*qt.basis(3,0) + 0.8*qt.basis(3,2)  # |ψ⟩ = 0.6|0⟩ + 0.8|2⟩
443
psi = psi.unit()  # Normalize
444
```
445

446
## Types
447

448
```python { .api }
449
# State construction functions return Qobj instances representing quantum states
450
# with appropriate dimensions and type attributes ('ket', 'bra', or 'oper' for density matrices)
451
```