Plot quantum states

Package versions

The code on this page was developed using the following requirements. We recommend using these versions or newer.

qiskit[all]~=1.2.4
qiskit-ibm-runtime~=0.33.2
qiskit-aer~=0.15.1
qiskit-serverless~=0.18.0
qiskit-ibm-catalog~=0.2
qiskit-addon-sqd~=0.8.0
qiskit-addon-utils~=0.1.0
qiskit-addon-aqc-tensor~=0.1.2
qiskit-addon-obp~=0.1.0
scipy~=1.14.1
pyscf~=2.7.0

In many situations – such as learning or debugging – it's helpful to visualize the state of a quantum computer. Here we assume you already have a particular state from simulation or state tomography. It's only possible to view the states of small quantum systems.

Using the output from functions

All functions on this page return rich objects. When the last line of a code cell outputs these objects, Jupyter notebooks display them below the cell. If you call these functions in some other environments or in scripts, you will need to explicitly show or save the outputs.

Most functions return images, which are matplotlib.Figure objects. Two options are:

Call .show() on the returned object to open the image in a new window (assuming your configured matplotlib backend is interactive).
Call .savefig("out.png") to save the figure to out.png in the current working directory. The savefig() method takes a path so you can adjust the location and filename where you're saving the output. For example, plot_state_city(psi).savefig("out.png").

The LaTeX outputs are IPython.display.Latex objects. The best option in a non-Jupyter environment is to avoid this output by either printing the state for a text representation, or switching to the latex_source drawer to return a LaTeX source string.

A quantum state is either a density matrix $\rho$ (Hermitian matrix) or statevector $|\psi\rangle$ (complex vector). The density matrix is related to the statevector by

$\rho = |\psi\rangle\langle \psi|,$

and is more general, as it can represent mixed states (positive sum of statevectors)

$\rho = \sum_k p_k |\psi_k\rangle\langle \psi_k |.$

Qiskit represents quantum states through the Statevector and DensityMatrix classes and provides many visualization functions. See the sections after the following the code cell to see how Qiskit's different visualization functions plot the following quantum state.

from math import pi
from qiskit import QuantumCircuit
from qiskit.quantum_info import Statevector
 
# Create a Bell state for demonstration
qc = QuantumCircuit(2)
qc.h(0)
qc.crx(pi / 2, 0, 1)
psi = Statevector(qc)

While not technically a "plot", Qiskit can render LaTeX representations of both Statevector and DensityMatrix objects that display nicely in Jupyter notebooks. These follow the standard mathematical conventions for writing down quantum states. Read more in Basics of quantum information: Single systems.

Statevectors default to "ket notation", whereas density matrices are displayed as a 2×2 matrix.

psi.draw("latex")  # psi is a Statevector object

Output:

$\frac{\sqrt{2}}{2} |00\rangle+\frac{1}{2} |01\rangle- \frac{i}{2} |11\rangle$

from qiskit.quantum_info import DensityMatrix
 
DensityMatrix(psi).draw("latex")  # convert to a DensityMatrix and draw

Output:

\begin{bmatrix} \frac{1}{2} & \frac{\sqrt{2}}{4} & 0 & \frac{\sqrt{2} i}{4} \\ \frac{\sqrt{2}}{4} & \frac{1}{4} & 0 & \frac{i}{4} \\ 0 & 0 & 0 & 0 \\ - \frac{\sqrt{2} i}{4} & - \frac{i}{4} & 0 & \frac{1}{4} \\ \end{bmatrix}

You can also replace "latex" with "latex_source" to get the raw LaTeX string.

This plot displays the real and imaginary parts of each density matrix element in two three-dimensional bar charts. It's called a "city" plot because the bars resemble skyscrapers in a city. The state we're plotting has the following density matrix.

\begin{bmatrix} \frac{1}{2} & \frac{\sqrt{2}}{4} & 0 & \frac{\sqrt{2} i}{4} \\ \frac{\sqrt{2}}{4} & \frac{1}{4} & 0 & \frac{i}{4} \\ 0 & 0 & 0 & 0 \\ - \frac{\sqrt{2} i}{4} & - \frac{i}{4} & 0 & \frac{1}{4} \\ \end{bmatrix} = \begin{bmatrix} \frac{1}{2} & \frac{\sqrt{2}}{4} & 0 & 0 \\ \frac{\sqrt{2}}{4} & \frac{1}{4} & 0 & 0 \\ 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & \frac{1}{4} \\ \end{bmatrix} + i \begin{bmatrix} 0 & 0 & 0 & \frac{\sqrt{2} i}{4} \\ 0 & 0 & 0 & \frac{i}{4} \\ 0 & 0 & 0 & 0 \\ - \frac{\sqrt{2} i}{4} & - \frac{i}{4} & 0 & 0 \\ \end{bmatrix}

from qiskit.visualization import plot_state_city
 
plot_state_city(psi)
# Alternative: psi.draw("city")

Output:

See the API documentation for more information.

This plot is very similar to the "city" plot, but the magnitude of each element is represented by the size of a square rather than the height of a bar. White squares represent elements with positive values, and black squares represent elements with negative values. The state we're plotting has the following density matrix.

\begin{bmatrix} \frac{1}{2} & \frac{\sqrt{2}}{4} & 0 & \frac{\sqrt{2} i}{4} \\ \frac{\sqrt{2}}{4} & \frac{1}{4} & 0 & \frac{i}{4} \\ 0 & 0 & 0 & 0 \\ - \frac{\sqrt{2} i}{4} & - \frac{i}{4} & 0 & \frac{1}{4} \\ \end{bmatrix} = \begin{bmatrix} \frac{1}{2} & \frac{\sqrt{2}}{4} & 0 & 0 \\ \frac{\sqrt{2}}{4} & \frac{1}{4} & 0 & 0 \\ 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & \frac{1}{4} \\ \end{bmatrix} + i \begin{bmatrix} 0 & 0 & 0 & \frac{\sqrt{2} i}{4} \\ 0 & 0 & 0 & \frac{i}{4} \\ 0 & 0 & 0 & 0 \\ - \frac{\sqrt{2} i}{4} & - \frac{i}{4} & 0 & 0 \\ \end{bmatrix}

from qiskit.visualization import plot_state_hinton
 
plot_state_hinton(psi)
# Alternative: psi.draw("hinton")

Output:

See the API documentation for more information.

An observable is a way of measuring a quantum state such that the possible measurement outcomes are real numbers. The expected value of the outcome is also known as the expectation value of the observable on that state, and it can be thought of as the average of infinitely many observations of that state.

Tensor products of Pauli matrices are all observables that return +1 or -1. This plot displays the expectation values of the state on different Pauli operators as a bar chart. All density matrices can be written as a sum of these Pauli matrices, weighted by their expectation values.

For example, this state can be written as the sum of terms:

|\psi\rangle\langle\psi| = \tfrac{1}{4}II + \tfrac{\sqrt{2}}{8}IX - \tfrac{\sqrt{2}}{8}XY - \tfrac{1}{8}YI - \tfrac{\sqrt{2}}{8}YX + \tfrac{1}{8}YZ + \tfrac{1}{8}ZI + \tfrac{\sqrt{2}}{8}ZX + \tfrac{1}{8}ZZ

from qiskit.visualization import plot_state_paulivec
 
plot_state_paulivec(psi)
# Alternative: psi.draw("paulivec")

Output:

You can also calculate these coefficients using SparsePauliOp.

from qiskit.quantum_info import SparsePauliOp
 
SparsePauliOp.from_operator(psi)

Output:

SparsePauliOp(['II', 'IX', 'XY', 'YI', 'YX', 'YZ', 'ZI', 'ZX', 'ZZ'],
              coeffs=[ 0.25     +0.j,  0.1767767+0.j, -0.1767767+0.j, -0.125    +0.j,
 -0.1767767+0.j,  0.125    +0.j,  0.125    +0.j,  0.1767767+0.j,
  0.125    +0.j])

See the API documentation for more information.

The "QSphere" is a Qiskit-unique view of a quantum state in which the amplitude and phase of each element in a statevector is plotted on the surface of a sphere. The thickness of each dot represents the amplitude, and the color represents the phase. For mixed states it will show a sphere for each component.

from qiskit.visualization import plot_state_qsphere
 
plot_state_qsphere(psi)
# Alternative: psi.draw("qsphere")

Output:

See the API documentation for more information.

The Bloch vector of a qubit state is its expectation value in the X, Y, and Z Pauli observables mapped to the X, Y, and Z axes in three-dimensional space. This plot projects multi-qubit quantum states onto the single-qubit space and plots each qubit on a Bloch sphere. This visualization only shows the expectation values of individual qubits. It can't show correlations between qubits and so can't fully describe entangled quantum states.

from qiskit.visualization import plot_bloch_multivector
 
plot_bloch_multivector(psi)
# Alternative: psi.draw("bloch")

Output:

See the API documentation for more information.

Options for state-plotting functions

All state-plotting functions accept the following arguments (except the LaTeX drawer, which doesn't return a Matplotlib figure, and plot_state_qsphere, which only accepts figsize):

title (str): a string for the plot title, displayed at the top of the plot
figsize (tuple): figure size in inches (width, height)

The plot_state_city and plot_state_paulivec functions also accept a color argument (list of strings) specifying the colors of the bars. See the API documentation for more information.

Qiskit Code Assistant

Can't remember the name of the plotting function you need? Try asking Qiskit Code Assistant.

# Plot psi on a Bloch sphere

# Plot a qsphere of psi with title 'Psi'

New to the code assistant? See Qiskit Code Assistant for installation and usage. Note this is an experimental feature and only available to IBM Quantum™ Premium Plan users.

Next steps

Recommendations

Need to refresh your quantum information knowledge? Check out the Basics of quantum information course on IBM Quantum Learning.
Read the contributing guidelines if you want to contribute to the open-source Qiskit SDK.