Quantum State Visualization

Functions for visualizing quantum state vectors and density matrices as 3D bar plots.

plot_state

Unified interface for plotting quantum state vectors or density matrices. Dispatches to the appropriate visualization based on the kind parameter.

Signature

python

plot_state(state, kind: str = 'city', title: str = '', figsize: Optional[tuple] = None)

Parameters

Parameter	Type	Description
state	array_like	Quantum state vector or density matrix
kind	`str`	Visualization type: `'city'` or `'density'` (default `'city'`)
title	`str`	Plot title (default `''`)
figsize	`tuple` or `None`	Figure size in inches, e.g. `(15, 5)` (default `None`)

Description

When kind='city', delegates to plot_state_city which renders side-by-side 3D bar charts of the real and imaginary parts of the density matrix. When kind='density', delegates to plot_density_matrix which renders a 3D bar chart with phase-based coloring.

Examples

python

import numpy as np
from pyqpanda3.visualization import plot_state

# Create a Bell state density matrix
state = np.array([1/np.sqrt(2), 0, 0, 1/np.sqrt(2)], dtype=complex)

# Plot as cityscape (real/imaginary 3D bars)
plot_state(state, kind='city', title='Bell State')

# Plot as density matrix (phase-colored 3D bars)
plot_state(state, kind='density', title='Bell State')

plot_state_city

Plots the real and imaginary parts of a quantum state density matrix as side-by-side 3D bar plots.

Signature

python

plot_state_city(state, title="", figsize=None, color=None, ax_real=None, ax_imag=None)

Parameters

Parameter	Type	Description
state	`list[complex]`	Quantum state vector or density matrix
title	`str`	Plot title (default `""`)
figsize	`tuple` or `None`	Figure size in inches (default `(15, 5)` when creating a new figure)
color	`list` or `None`	A list of two colors for the real and imaginary parts, e.g. `["#648fff", "#648fff"]` (default `None`)
ax_real	`matplotlib.axes.Axes` or `None`	Existing 3D axes for the real part plot (default `None`)
ax_imag	`matplotlib.axes.Axes` or `None`	Existing 3D axes for the imaginary part plot (default `None`)

Returns

matplotlib.figure.Figure -- The figure object containing the plots.

Description

Converts the input state to a density matrix via state_to_density_matrix, then renders two 3D bar charts: the left chart shows the real part of $ρ$ and the right chart shows the imaginary part of $ρ$ . Each bar corresponds to an element of the density matrix, with x/y axes labeled using binary state strings.

When ax_real and ax_imag are both None, a new figure is created. Pass existing axes to embed the plot into a custom figure layout.

Examples

python

import numpy as np
from pyqpanda3.visualization import plot_state_city

# Bell state vector
state = np.array([1/np.sqrt(2), 0, 0, 1/np.sqrt(2)], dtype=complex)

# Basic plot
plot_state_city(state, title="Bell State (City Plot)")

# Custom colors and figure size
plot_state_city(state, title="Custom Colors", figsize=(12, 4), color=["#e76f51", "#2a9d8f"])

# Plot onto existing axes
import matplotlib.pyplot as plt
fig = plt.figure(figsize=(12, 4))
ax1 = fig.add_subplot(1, 2, 1, projection='3d')
ax2 = fig.add_subplot(1, 2, 2, projection='3d')
plot_state_city(state, ax_real=ax1, ax_imag=ax2, title="Embedded Plot")

plot_density_matrix

Plots a density matrix as a 3D bar chart where bar height represents the absolute value and color represents the complex phase.

Signature

python

plot_density_matrix(M, xlabels=None, ylabels=None,
                    title=None, limits=None, phase_limits=None, fig=None, axis_vals=None,
                    threshold=None)

Parameters

Parameter	Type	Description
M	`list[complex]` or `numpy.ndarray`	Density matrix (2D array of complex numbers)
xlabels	`list[str]` or `None`	Labels for the x-axis ticks (default `None`)
ylabels	`list[str]` or `None`	Labels for the y-axis ticks (default `None`)
title	`str` or `None`	Plot title (default `None`)
limits	`list` or `None`	Z-axis limits as `[z_min, z_max]` (default `None`, auto-scaled)
phase_limits	`list` or `None`	Phase angle range as `[phase_min, phase_max]` in radians (default `[-pi, pi]`)
fig	`matplotlib.figure.Figure` or `None`	Existing figure object to plot on (default `None`)
axis_vals	`matplotlib.axes.Axes` or `None`	Existing 3D axis object to plot on (default `None`)
threshold	`float` or `None`	Only show bars with absolute value above this threshold (default `None`)

Returns

tuple -- A tuple of (fig, axis_vals) containing the figure and 3D axes objects.

Description

Renders a 3D bar chart of the density matrix where each bar's height is the absolute value $| ρ_{i j} |$ and its color encodes the complex phase $\arg (ρ_{i j})$ using a cyclic colormap. A colorbar maps the phase from $- π$ to $π$ . Bars with very small absolute values (below 0.001) are treated as real to avoid random coloring from noise.

Examples

python

import numpy as np
from pyqpanda3.visualization import plot_density_matrix

# Construct a Bell state density matrix
psi = np.array([1/np.sqrt(2), 0, 0, 1/np.sqrt(2)], dtype=complex)
rho = np.outer(psi, np.conj(psi))

# Basic plot
plot_density_matrix(rho, title="Bell State Density Matrix")

# With custom labels and z-axis limits
labels = ["00", "01", "10", "11"]
plot_density_matrix(rho, xlabels=labels, ylabels=labels,
                    title="Bell State", limits=[0, 0.6])

# With phase threshold to filter small elements
plot_density_matrix(rho, title="Threshold Filtered", threshold=0.01)

state_to_density_matrix

Converts a quantum state vector to its density matrix representation. If the input is already a density matrix, it is validated and returned.

Signature

python

state_to_density_matrix(quantum_state)

Parameters

Parameter	Type	Description
quantum_state	`list[complex]` or `numpy.ndarray`	Quantum state vector (1D array) or density matrix (2D square array)

Returns

numpy.ndarray -- The density matrix as a 2D complex array.

Description

For a state vector $| ψ ⟩$ , computes $ρ = | ψ ⟩ ⟨ ψ |$ . If the input is already a density matrix, validates that it is a square matrix with dimension $2^{n}$ for some integer $n$ .

Raises RuntimeError if the input is not a valid quantum state (not a 2^n-dimensional state vector or not a valid square density matrix).

Examples

python

import numpy as np
from pyqpanda3.visualization import state_to_density_matrix

# Convert a state vector to density matrix
psi = np.array([1/np.sqrt(2), 0, 0, 1/np.sqrt(2)], dtype=complex)
rho = state_to_density_matrix(psi)
print(rho)
# [[0.5+0.j 0. +0.j 0. +0.j 0.5+0.j]
#  [0. +0.j 0. +0.j 0. +0.j 0. +0.j]
#  [0. +0.j 0. +0.j 0. +0.j 0. +0.j]
#  [0.5+0.j 0. +0.j 0. +0.j 0.5+0.j]]

# Passing a density matrix directly returns it (after validation)
rho2 = state_to_density_matrix(rho)

Quantum State Visualization ​

plot_state ​

Signature ​

Parameters ​

Description ​

Examples ​

plot_state_city ​

Signature ​

Parameters ​

Returns ​

Description ​

Examples ​

plot_density_matrix ​

Signature ​

Parameters ​

Returns ​

Description ​

Examples ​

state_to_density_matrix ​

Signature ​

Parameters ​

Returns ​

Description ​

Examples ​

See Also ​

Quantum State Visualization

plot_state

Signature

Parameters

Description

Examples

plot_state_city

Signature

Parameters

Returns

Description

Examples

plot_density_matrix

Signature

Parameters

Returns

Description

Examples

state_to_density_matrix

Signature

Parameters

Returns

Description

Examples

See Also