量子态可视化

用于将量子态矢量和密度矩阵可视化为 3D 柱状图的函数。

plot_state

绘制量子态矢量或密度矩阵的统一接口。根据 kind 参数分派到相应的可视化方法。

签名

python

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

参数

参数	类型	说明
state	array_like	量子态矢量或密度矩阵
kind	`str`	可视化类型：`'city'` 或 `'density'`（默认 `'city'`）
title	`str`	图表标题（默认 `''`）
figsize	`tuple` 或 `None`	图形尺寸（英寸），例如 `(15, 5)`（默认 `None`）

说明

当 kind='city' 时，委托给 plot_state_city，该函数会并排渲染密度矩阵实部和虚部的 3D 柱状图。当 kind='density' 时，委托给 plot_density_matrix，该函数会渲染基于相位着色的 3D 柱状图。

示例

python

import numpy as np
from pyqpanda3.visualization import plot_state

# Create a Bell state vector
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')

# Create a density matrix and plot as phase-colored 3D bars
rho = np.outer(state, np.conj(state))
plot_state(rho, kind='density', title='Bell State')

plot_state_city

将量子态密度矩阵的实部和虚部绘制为并排的 3D 柱状图。

签名

python

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

参数

参数	类型	说明
state	`list[complex]`	量子态矢量或密度矩阵
title	`str`	图表标题（默认 `""`）
figsize	`tuple` 或 `None`	图形尺寸（英寸）（创建新图形时默认 `(15, 5)`）
color	`list` 或 `None`	实部和虚部使用的两种颜色列表，例如 `["#648fff", "#648fff"]`（默认 `None`）
ax_real	`matplotlib.axes.Axes` 或 `None`	用于实部绘图的现有 3D 坐标轴（默认 `None`）
ax_imag	`matplotlib.axes.Axes` 或 `None`	用于虚部绘图的现有 3D 坐标轴（默认 `None`）

返回值

matplotlib.figure.Figure 或 None -- 创建新图形时返回图形对象；通过 ax_real 和 ax_imag 传入现有坐标轴时返回 None。

说明

通过 state_to_density_matrix 将输入状态转换为密度矩阵，然后渲染两个 3D 柱状图：左侧图表显示 $ρ$ 的实部，右侧图表显示 $ρ$ 的虚部。每个柱体对应密度矩阵的一个元素，x/y 轴使用二进制状态字符串标注。

当 ax_real 和 ax_imag 均为 None 时，将创建一个新图形。传入现有坐标轴可将绘图嵌入到自定义图形布局中。

示例

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

将密度矩阵绘制为 3D 柱状图，其中柱体高度表示绝对值，颜色表示复数相位。

签名

python

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

参数

参数	类型	说明
M	`list[complex]` 或 `numpy.ndarray`	密度矩阵（复数的二维数组）
xlabels	`list[str]` 或 `None`	x 轴刻度标签（默认 `None`）
ylabels	`list[str]` 或 `None`	y 轴刻度标签（默认 `None`）
title	`str` 或 `None`	图表标题（默认 `None`）
limits	`list` 或 `None`	z 轴范围，格式为 `[z_min, z_max]`（默认 `None`，自动缩放）
phase_limits	`list` 或 `None`	相位角范围，格式为 `[phase_min, phase_max]`，单位为弧度（默认 `[-pi, pi]`）
fig	`matplotlib.figure.Figure` 或 `None`	用于绘图的现有图形对象（默认 `None`）
axis_vals	`matplotlib.axes.Axes` 或 `None`	用于绘图的现有 3D 坐标轴对象（默认 `None`）
threshold	`float` 或 `None`	仅显示绝对值大于此阈值的柱体（默认 `None`）

返回值

tuple -- 包含 (fig, axis_vals) 的元组，即图形和 3D 坐标轴对象。

说明

渲染密度矩阵的 3D 柱状图，其中每个柱体的高度为绝对值 $| ρ_{i j} |$ ，颜色使用循环色图编码复数相位 $\arg (ρ_{i j})$ 。颜色条将相位映射从 $- π$ 到 $π$ 。绝对值非常小的柱体（低于 0.001）会被视为实数，以避免噪声导致的随机着色。

示例

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

将量子态矢量转换为其密度矩阵表示。如果输入已经是密度矩阵，则验证后返回。

签名

python

state_to_density_matrix(quantum_state)

参数

参数	类型	说明
quantum_state	`list[complex]` 或 `numpy.ndarray`	量子态矢量（一维数组）或密度矩阵（二维方阵）

返回值

numpy.ndarray -- 密度矩阵，二维复数数组。

说明

对于态矢量 $| ψ ⟩$ ，计算 $ρ = | ψ ⟩ ⟨ ψ |$ 。如果输入已经是密度矩阵，则验证它是否为维度为 $2^{n}$ （n 为整数）的方阵。

如果输入不是有效的量子态（非 $2^{n}$ 维态矢量或非有效方阵密度矩阵），将抛出 RuntimeError。

示例

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)

运行结果：

[[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]]

另见

电路可视化 -- 电路绘制和文本输出函数
Bloch 球 -- Bloch 球可视化函数

量子态可视化 ​

plot_state ​

签名 ​

参数 ​

说明 ​

示例 ​

plot_state_city ​

签名 ​

参数 ​

返回值 ​

说明 ​

示例 ​

plot_density_matrix ​

签名 ​

参数 ​

返回值 ​

说明 ​

示例 ​

state_to_density_matrix ​

签名 ​

参数 ​

返回值 ​

说明 ​

示例 ​

另见 ​

量子态可视化

plot_state

签名

参数

说明

示例

plot_state_city

签名

参数

返回值

说明

示例

plot_density_matrix

签名

参数

返回值

说明

示例

state_to_density_matrix

签名

参数

返回值

说明

示例

另见