Skip to main contentIBM Quantum Documentation

Plot quantum states

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)

ρ=kpkψkψk.\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.

[1] :
from math import pi
from qiskit import QuantumCircuit
from qiskit.quantum_info import Statevector
# Create a Bell state for demonstration
qc = QuantumCircuit(2)
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(opens in a new tab).

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

[2] :
psi.draw("latex")  # psi is a Statevector object


2200+1201i211\frac{\sqrt{2}}{2} |00\rangle+\frac{1}{2} |01\rangle- \frac{i}{2} |11\rangle

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


[122402i424140i400002i4i4014] \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.

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.

Next steps

Was this page helpful?
Report a bug or request content on GitHub.