0
# Visualization and Graphics
1
2
Comprehensive visualization tools for quantum states, processes, and dynamics including Bloch sphere, Wigner functions, and matrix representations.
3
4
## Capabilities
5
6
### Bloch Sphere Visualization
7
8
Three-dimensional visualization of qubit states on the Bloch sphere.
9
10
```python { .api }
11
class Bloch:
12
"""
13
Bloch sphere visualization for qubit states and operations.
14
"""
15
def __init__(self, fig=None, axes=None, view=None, figsize=None, background=False):
16
"""
17
Initialize Bloch sphere.
18
19
Parameters:
20
- fig: Matplotlib figure object
21
- axes: Matplotlib 3D axes object
22
- view: Viewing angle [azimuth, elevation]
23
- figsize: Figure size tuple
24
- background: Use dark background
25
"""
26
27
def add_states(self, state, kind='vector'):
28
"""
29
Add quantum states to Bloch sphere.
30
31
Parameters:
32
- state: Qobj state or list of states
33
- kind: 'vector' for pure states, 'point' for density matrices
34
"""
35
36
def add_vectors(self, list_of_vectors):
37
"""
38
Add vectors to Bloch sphere.
39
40
Parameters:
41
- list_of_vectors: List of [x,y,z] coordinate vectors
42
"""
43
44
def add_points(self, list_of_points, meth='s'):
45
"""
46
Add points to Bloch sphere.
47
48
Parameters:
49
- list_of_points: List of [x,y,z] coordinates
50
- meth: Point style ('s' for scatter, 'l' for line)
51
"""
52
53
def render(self, title=''):
54
"""
55
Render the Bloch sphere.
56
57
Parameters:
58
- title: Plot title
59
"""
60
61
def show(self):
62
"""Display the Bloch sphere plot."""
63
64
def clear(self):
65
"""Clear all vectors and points from sphere."""
66
67
def save(self, name=None, format='png', dirc=None):
68
"""
69
Save Bloch sphere to file.
70
71
Parameters:
72
- name: Filename
73
- format: File format ('png', 'svg', 'pdf')
74
- dirc: Directory path
75
"""
76
```
77
78
### Matrix Visualization
79
80
Various methods for visualizing quantum operators and density matrices.
81
82
```python { .api }
83
def hinton(rho: Qobj, xlabels=None, ylabels=None, title=None, ax=None, cmap=None, label_top=True) -> None:
84
"""
85
Create Hinton diagram for visualizing matrix elements.
86
87
Parameters:
88
- rho: Quantum object to visualize
89
- xlabels: Labels for x-axis
90
- ylabels: Labels for y-axis
91
- title: Plot title
92
- ax: Matplotlib axes object
93
- cmap: Colormap
94
- label_top: Place labels on top
95
"""
96
97
def matrix_histogram(M: Qobj, xlabels=None, ylabels=None, title=None, limits=None, ax=None) -> None:
98
"""
99
Create 3D histogram of matrix elements.
100
101
Parameters:
102
- M: Matrix to visualize (Qobj)
103
- xlabels: X-axis labels
104
- ylabels: Y-axis labels
105
- title: Plot title
106
- limits: Color scale limits [min, max]
107
- ax: Matplotlib axes object
108
"""
109
110
def matrix_histogram_complex(M: Qobj, xlabels=None, ylabels=None, title=None, limits=None, ax=None, threshold=0.01) -> None:
111
"""
112
Create 3D histogram for complex matrix elements.
113
114
Parameters:
115
- M: Complex matrix to visualize
116
- xlabels: X-axis labels
117
- ylabels: Y-axis labels
118
- title: Plot title
119
- limits: Color scale limits
120
- ax: Matplotlib axes
121
- threshold: Minimum value to display
122
"""
123
```
124
125
### Phase Space Visualization
126
127
Wigner functions and Q-functions for continuous variable systems.
128
129
```python { .api }
130
def plot_wigner(rho: Qobj, xvec=None, yvec=None, method='clenshaw', projection='2d',
131
g=np.sqrt(2), sparse=False, parfor=False) -> tuple:
132
"""
133
Plot Wigner function in phase space.
134
135
Parameters:
136
- rho: Density matrix or state vector
137
- xvec: X-coordinate array for phase space
138
- yvec: Y-coordinate array for phase space
139
- method: 'clenshaw', 'iterative', or 'laguerre'
140
- projection: '2d' for contour, '3d' for surface plot
141
- g: Scaling factor (default √2)
142
- sparse: Use sparse matrices
143
- parfor: Use parallel computation
144
145
Returns:
146
- tuple: (figure, axes) matplotlib objects
147
"""
148
149
def plot_qfunc(rho: Qobj, xvec=None, yvec=None, projection='2d', g=np.sqrt(2)) -> tuple:
150
"""
151
Plot Q-function (Husimi distribution) in phase space.
152
153
Parameters:
154
- rho: Density matrix or state vector
155
- xvec: X-coordinate array
156
- yvec: Y-coordinate array
157
- projection: '2d' for contour, '3d' for surface
158
- g: Scaling factor
159
160
Returns:
161
- tuple: (figure, axes) matplotlib objects
162
"""
163
164
def plot_wigner_sphere(rho: Qobj, fig=None, ax=None, colorbar=True,
165
cmap='RdBu', alpha=0.7) -> tuple:
166
"""
167
Plot spin Wigner function on sphere surface.
168
169
Parameters:
170
- rho: Spin density matrix
171
- fig: Matplotlib figure
172
- ax: 3D axes object
173
- colorbar: Show colorbar
174
- cmap: Colormap name
175
- alpha: Transparency
176
177
Returns:
178
- tuple: (figure, axes)
179
"""
180
```
181
182
### Fock State and Distribution Plots
183
184
Visualization of photon number distributions and Fock state properties.
185
186
```python { .api }
187
def plot_fock_distribution(rho: Qobj, offset=0, fig=None, ax=None, figsize=(8,6),
188
title=None, unit_y_range=True) -> tuple:
189
"""
190
Plot Fock state distribution (photon number probabilities).
191
192
Parameters:
193
- rho: Density matrix
194
- offset: Fock state index offset
195
- fig: Matplotlib figure
196
- ax: Matplotlib axes
197
- figsize: Figure size
198
- title: Plot title
199
- unit_y_range: Normalize y-axis to [0,1]
200
201
Returns:
202
- tuple: (figure, axes)
203
"""
204
205
def plot_energy_levels(H_list, N=0, labels=None, show_ylabels=False, fig=None, ax=None) -> tuple:
206
"""
207
Plot energy level diagrams for quantum systems.
208
209
Parameters:
210
- H_list: List of Hamiltonian operators
211
- N: Number of energy levels to plot (0 for all)
212
- labels: List of system labels
213
- show_ylabels: Show y-axis labels
214
- fig: Matplotlib figure
215
- ax: Matplotlib axes
216
217
Returns:
218
- tuple: (figure, axes)
219
"""
220
```
221
222
### Expectation Value and Time Evolution Plots
223
224
Visualization of quantum dynamics and expectation values.
225
226
```python { .api }
227
def plot_expectation_values(results, e_ops, show_legend=True, fig=None, axes=None,
228
figsize=(8,6)) -> tuple:
229
"""
230
Plot expectation values from solver results.
231
232
Parameters:
233
- results: Result object from solver
234
- e_ops: List of expectation value operators
235
- show_legend: Display legend
236
- fig: Matplotlib figure
237
- axes: Matplotlib axes
238
- figsize: Figure size
239
240
Returns:
241
- tuple: (figure, axes)
242
"""
243
```
244
245
### Spin System Visualization
246
247
Specialized visualization for spin systems and angular momentum.
248
249
```python { .api }
250
def plot_spin_distribution(rho: Qobj, theta=None, phi=None, fig=None, ax=None) -> tuple:
251
"""
252
Plot spin state distribution on sphere.
253
254
Parameters:
255
- rho: Spin density matrix
256
- theta: Polar angle array
257
- phi: Azimuthal angle array
258
- fig: Matplotlib figure
259
- ax: 3D axes object
260
261
Returns:
262
- tuple: (figure, axes)
263
"""
264
265
def sphereplot(theta, phi, values, fig=None, ax=None, save=False) -> tuple:
266
"""
267
Plot values on sphere surface.
268
269
Parameters:
270
- theta: Polar angles
271
- phi: Azimuthal angles
272
- values: Values to plot on sphere
273
- fig: Matplotlib figure
274
- ax: 3D axes
275
- save: Save plot to file
276
277
Returns:
278
- tuple: (figure, axes)
279
"""
280
```
281
282
### Complex Array and Quantum State Visualization
283
284
Advanced visualization techniques for quantum states and complex data.
285
286
```python { .api }
287
def complex_array_to_rgb(X, theme='light', rmax=None, phase_limits=(-np.pi, np.pi)) -> np.ndarray:
288
"""
289
Convert complex array to RGB colors for visualization.
290
291
Parameters:
292
- X: Complex array
293
- theme: 'light' or 'dark' color theme
294
- rmax: Maximum radius for scaling
295
- phase_limits: Phase range limits
296
297
Returns:
298
- ndarray: RGB color array
299
"""
300
301
def plot_qubism(ket, legend_iteration=0, fig=None, ax=None, figsize=(8,8),
302
title=True, grid=False, color_style='default') -> tuple:
303
"""
304
Plot qubism representation of multi-qubit state.
305
306
Parameters:
307
- ket: Multi-qubit state vector
308
- legend_iteration: Legend iteration number
309
- fig: Matplotlib figure
310
- ax: Matplotlib axes
311
- figsize: Figure size
312
- title: Show title
313
- grid: Show grid
314
- color_style: Color scheme
315
316
Returns:
317
- tuple: (figure, axes)
318
"""
319
320
def plot_schmidt(ket, splitting=None, labels_iteration=None, title=True,
321
fig=None, ax=None, figsize=(8,6)) -> tuple:
322
"""
323
Plot Schmidt decomposition of bipartite quantum state.
324
325
Parameters:
326
- ket: Bipartite state vector
327
- splitting: Subsystem dimension splitting
328
- labels_iteration: Label iteration for multi-time analysis
329
- title: Show plot title
330
- fig: Matplotlib figure
331
- ax: Matplotlib axes
332
- figsize: Figure size
333
334
Returns:
335
- tuple: (figure, axes)
336
"""
337
```
338
339
### Colormap and Utility Functions
340
341
Specialized colormaps and utilities for quantum visualization.
342
343
```python { .api }
344
def wigner_cmap(W, levels=1024, shift=0, invert=False) -> object:
345
"""
346
Create colormap for Wigner function visualization.
347
348
Parameters:
349
- W: Wigner function data
350
- levels: Number of color levels
351
- shift: Phase shift for colors
352
- invert: Invert colormap
353
354
Returns:
355
- object: Matplotlib colormap
356
"""
357
```
358
359
### Usage Examples
360
361
```python
362
import qutip as qt
363
import numpy as np
364
import matplotlib.pyplot as plt
365
366
# Qubit state visualization on Bloch sphere
367
psi = (qt.basis(2,0) + qt.basis(2,1)).unit() # |+⟩ state
368
b = qt.Bloch()
369
b.add_states(psi)
370
b.render()
371
b.show()
372
373
# Add multiple states and vectors
374
states = [qt.basis(2,0), qt.basis(2,1), (qt.basis(2,0) + qt.basis(2,1)).unit()]
375
b = qt.Bloch()
376
b.add_states(states)
377
b.add_vectors([[0,0,1], [1,0,0]]) # Add custom vectors
378
b.show()
379
380
# Hinton diagram for density matrix
381
rho = qt.bell_state().ptrace(0) # Mixed state from Bell state
382
qt.hinton(rho, title='Reduced density matrix')
383
plt.show()
384
385
# Matrix histogram visualization
386
H = qt.rand_herm(4) # Random Hermitian matrix
387
qt.matrix_histogram(H, title='Random Hamiltonian')
388
plt.show()
389
390
# Wigner function for coherent state
391
alpha = 1.5 + 0.8j
392
rho_coh = qt.coherent_dm(20, alpha)
393
qt.plot_wigner(rho_coh, projection='2d')
394
plt.title('Wigner function of coherent state')
395
plt.show()
396
397
# 3D Wigner function plot
398
fig, ax = qt.plot_wigner(rho_coh, projection='3d')
399
plt.show()
400
401
# Q-function visualization
402
qt.plot_qfunc(rho_coh)
403
plt.title('Q-function of coherent state')
404
plt.show()
405
406
# Fock distribution plot
407
thermal_state = qt.thermal_dm(15, 2.5) # Thermal state
408
qt.plot_fock_distribution(thermal_state, title='Thermal state distribution')
409
plt.show()
410
411
# Energy level diagram
412
N = 5
413
H1 = qt.num(N) # Number operator
414
H2 = (qt.create(N) + qt.destroy(N)) # Position-like
415
H3 = -1j * (qt.create(N) - qt.destroy(N)) # Momentum-like
416
qt.plot_energy_levels([H1, H2, H3], labels=['Number', 'Position', 'Momentum'])
417
plt.show()
418
419
# Time evolution visualization
420
times = np.linspace(0, 10, 100)
421
H = qt.sigmaz()
422
result = qt.sesolve(H, qt.basis(2,0), times, e_ops=[qt.sigmax(), qt.sigmay(), qt.sigmaz()])
423
qt.plot_expectation_values(result, [qt.sigmax(), qt.sigmay(), qt.sigmaz()])
424
plt.show()
425
426
# Spin Wigner function on sphere
427
j = 1 # Spin-1 system
428
rho_spin = qt.spin_coherent(j, np.pi/3, np.pi/4, type='dm')
429
qt.plot_wigner_sphere(rho_spin)
430
plt.show()
431
432
# Multi-qubit state visualization (qubism)
433
ghz3 = qt.ghz_state(3)
434
qt.plot_qubism(ghz3, title=True)
435
plt.show()
436
437
# Schmidt decomposition plot
438
bell = qt.bell_state('00')
439
qt.plot_schmidt(bell, splitting=[2,2])
440
plt.show()
441
442
# Animation example (requires additional setup)
443
states = [qt.spin_coherent(0.5, theta, 0) for theta in np.linspace(0, np.pi, 20)]
444
# qt.anim_bloch(states) - for animated Bloch sphere
445
446
# Complex visualization
447
psi_complex = qt.rand_ket(10)
448
data = psi_complex.full().flatten()
449
rgb_colors = qt.complex_array_to_rgb(data)
450
plt.imshow(rgb_colors.reshape(10,1,3))
451
plt.title('Complex quantum state visualization')
452
plt.show()
453
```
454
455
## Types
456
457
```python { .api }
458
class Bloch:
459
"""
460
Bloch sphere visualization class.
461
462
Main Attributes:
463
vector_color: List of colors for state vectors
464
point_color: List of colors for points
465
vector_width: Width of state vectors
466
point_size: Size of points
467
sphere_color: Color of Bloch sphere
468
frame_color: Color of sphere frame
469
xlabel: X-axis label (default ['$x$'])
470
ylabel: Y-axis label (default ['$y$'])
471
zlabel: Z-axis label (default ['$z$'])
472
"""
473
474
# Visualization functions return matplotlib figure and axes objects as tuples
475
# or None for in-place plotting functions like hinton() and matrix_histogram()
476
```