{
"cells": [
{
"cell_type": "markdown",
"id": "fe606dcf-9205-4eb6-a789-0d66ae7dddec",
"metadata": {},
"source": [
"---\n",
"title: Plot quantum states\n",
"description: Visualize statevectors and density matrices using Qiskit\n",
"---\n",
"\n",
"# Plot quantum states\n",
"\n"
]
},
{
"cell_type": "markdown",
"id": "aa428131-c6fd-47cf-a2ac-9dcebe93b799",
"metadata": {
"tags": [
"version-info"
]
},
"source": [
"{/*\n",
" DO NOT EDIT THIS CELL!!!\n",
" This cell's content is generated automatically by a script. Anything you add\n",
" here will be removed next time the notebook is run. To add new content, create\n",
" a new cell before or after this one.\n",
" */}\n",
"\n",
"\n",
" \n",
" The code on this page was developed using the following requirements.\n",
" We recommend using these versions or newer.\n",
"\n",
" ```\n",
" qiskit[all]~=2.4.0\n",
" ```\n",
" \n",
"\n",
"\n"
]
},
{
"cell_type": "markdown",
"id": "e0242a86-db2b-4cdd-835e-4aa8a5349fb8",
"metadata": {},
"source": [
"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.\n",
"\n",
"\n",
" 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.\n",
"\n",
" Most functions return images, which are `matplotlib.Figure` objects. Two options are:\n",
"\n",
" * Call `.show()` on the returned object to open the image in a new window (assuming your configured matplotlib backend is interactive).\n",
" * 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\")`.\n",
"\n",
" 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.\n",
"\n",
"\n",
"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\n",
"\n",
"$\\rho = |\\psi\\rangle\\langle \\psi|,$\n",
"\n",
"and is more general, as it can represent mixed states (positive sum of statevectors)\n",
"\n",
"$\\rho = \\sum_k p_k |\\psi_k\\rangle\\langle \\psi_k |.$\n",
"\n",
"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.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "da6c51a7-813b-4fb0-bff0-bfc2010f9c49",
"metadata": {},
"outputs": [],
"source": [
"from math import pi\n",
"from qiskit import QuantumCircuit\n",
"from qiskit.quantum_info import Statevector\n",
"\n",
"# Create a Bell state for demonstration\n",
"qc = QuantumCircuit(2)\n",
"qc.h(0)\n",
"qc.crx(pi / 2, 0, 1)\n",
"psi = Statevector(qc)"
]
},
{
"cell_type": "markdown",
"id": "3a89d7cd-7eb2-499e-a9a4-e1921aa57284",
"metadata": {},
"source": [
"\n",
" \n",
" 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](/learning/courses/basics-of-quantum-information/single-systems/introduction).\n",
"\n",
" Statevectors default to \"ket notation\", whereas density matrices are displayed as a 2×2 matrix.\n",
"\n",
" \n",
"\n",
" \n",
"\n",
" You can also replace `\"latex\"` with `\"latex_source\"` to get the raw LaTeX string.\n",
" \n",
"\n",
" \n",
" 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.\n",
"\n",
" $$\n",
" \\begin{bmatrix}\n",
" \\frac{1}{2} & \\frac{\\sqrt{2}}{4} & 0 & \\frac{\\sqrt{2} i}{4} \\\\\n",
" \\frac{\\sqrt{2}}{4} & \\frac{1}{4} & 0 & \\frac{i}{4} \\\\\n",
" 0 & 0 & 0 & 0 \\\\\n",
" - \\frac{\\sqrt{2} i}{4} & - \\frac{i}{4} & 0 & \\frac{1}{4} \\\\\n",
" \\end{bmatrix}\n",
" =\n",
" \\begin{bmatrix}\n",
" \\frac{1}{2} & \\frac{\\sqrt{2}}{4} & 0 & 0 \\\\\n",
" \\frac{\\sqrt{2}}{4} & \\frac{1}{4} & 0 & 0 \\\\\n",
" 0 & 0 & 0 & 0 \\\\\n",
" 0 & 0 & 0 & \\frac{1}{4} \\\\\n",
" \\end{bmatrix}\n",
" + i\n",
" \\begin{bmatrix}\n",
" 0 & 0 & 0 & \\frac{\\sqrt{2} i}{4} \\\\\n",
" 0 & 0 & 0 & \\frac{i}{4} \\\\\n",
" 0 & 0 & 0 & 0 \\\\\n",
" - \\frac{\\sqrt{2} i}{4} & - \\frac{i}{4} & 0 & 0 \\\\\n",
" \\end{bmatrix}\n",
" $$\n",
"\n",
" \n",
"\n",
" See the [API documentation](/docs/api/qiskit/qiskit.visualization.plot_state_city) for more information.\n",
" \n",
"\n",
" \n",
" 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.\n",
"\n",
" $$\n",
" \\begin{bmatrix}\n",
" \\frac{1}{2} & \\frac{\\sqrt{2}}{4} & 0 & \\frac{\\sqrt{2} i}{4} \\\\\n",
" \\frac{\\sqrt{2}}{4} & \\frac{1}{4} & 0 & \\frac{i}{4} \\\\\n",
" 0 & 0 & 0 & 0 \\\\\n",
" - \\frac{\\sqrt{2} i}{4} & - \\frac{i}{4} & 0 & \\frac{1}{4} \\\\\n",
" \\end{bmatrix}\n",
" =\n",
" \\begin{bmatrix}\n",
" \\frac{1}{2} & \\frac{\\sqrt{2}}{4} & 0 & 0 \\\\\n",
" \\frac{\\sqrt{2}}{4} & \\frac{1}{4} & 0 & 0 \\\\\n",
" 0 & 0 & 0 & 0 \\\\\n",
" 0 & 0 & 0 & \\frac{1}{4} \\\\\n",
" \\end{bmatrix}\n",
" + i\n",
" \\begin{bmatrix}\n",
" 0 & 0 & 0 & \\frac{\\sqrt{2} i}{4} \\\\\n",
" 0 & 0 & 0 & \\frac{i}{4} \\\\\n",
" 0 & 0 & 0 & 0 \\\\\n",
" - \\frac{\\sqrt{2} i}{4} & - \\frac{i}{4} & 0 & 0 \\\\\n",
" \\end{bmatrix}\n",
" $$\n",
"\n",
" \n",
"\n",
" See the [API documentation](/docs/api/qiskit/qiskit.visualization.plot_state_hinton) for more information.\n",
" \n",
"\n",
" \n",
" 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.\n",
"\n",
" 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.\n",
"\n",
" For example, this state can be written as the sum of terms:\n",
"\n",
" $$\n",
" |\\psi\\rangle\\langle\\psi|\n",
" =\n",
" \\tfrac{1}{4}II\n",
" + \\tfrac{\\sqrt{2}}{8}IX\n",
" - \\tfrac{\\sqrt{2}}{8}XY\n",
" - \\tfrac{1}{8}YI\n",
" - \\tfrac{\\sqrt{2}}{8}YX\n",
" + \\tfrac{1}{8}YZ\n",
" + \\tfrac{1}{8}ZI\n",
" + \\tfrac{\\sqrt{2}}{8}ZX\n",
" + \\tfrac{1}{8}ZZ\n",
" $$\n",
"\n",
" \n",
"\n",
" You can also calculate these coefficients using `SparsePauliOp`.\n",
"\n",
" \n",
"\n",
" See the [API documentation](/docs/api/qiskit/qiskit.visualization.plot_state_paulivec) for more information.\n",
" \n",
"\n",
" \n",
" 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.\n",
"\n",
" \n",
"\n",
" See the [API documentation](/docs/api/qiskit/qiskit.visualization.plot_state_qsphere) for more information.\n",
" \n",
"\n",
" \n",
" 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.\n",
"\n",
" \n",
"\n",
" See the [API documentation](/docs/api/qiskit/qiskit.visualization.plot_bloch_multivector) for more information.\n",
" \n",
"\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "f6a47fc5-8b71-416d-8982-7e89a483d2e5",
"metadata": {
"tags": [
"id-tabs-latex"
]
},
"outputs": [
{
"data": {
"text/latex": [
"$$\\frac{\\sqrt{2}}{2} |00\\rangle+\\frac{1}{2} |01\\rangle- \\frac{i}{2} |11\\rangle$$"
],
"text/plain": [
""
]
},
"execution_count": 2,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"psi.draw(\"latex\") # psi is a Statevector object"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "9b6c950a-d2b1-48d0-95ff-4b44fb897697",
"metadata": {
"tags": [
"id-tabs-latex-2"
]
},
"outputs": [
{
"data": {
"text/latex": [
"$$\n",
"\n",
"\\begin{bmatrix}\n",
"\\frac{1}{2} & \\frac{\\sqrt{2}}{4} & 0 & \\frac{\\sqrt{2} i}{4} \\\\\n",
" \\frac{\\sqrt{2}}{4} & \\frac{1}{4} & 0 & \\frac{i}{4} \\\\\n",
" 0 & 0 & 0 & 0 \\\\\n",
" - \\frac{\\sqrt{2} i}{4} & - \\frac{i}{4} & 0 & \\frac{1}{4} \\\\\n",
" \\end{bmatrix}\n",
"$$"
],
"text/plain": [
""
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from qiskit.quantum_info import DensityMatrix\n",
"\n",
"DensityMatrix(psi).draw(\"latex\") # convert to a DensityMatrix and draw"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "752f7232-dfe5-457b-82f1-8a4ab5837aef",
"metadata": {
"tags": [
"id-tabs-city"
]
},
"outputs": [
{
"data": {
"text/plain": [
""
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from qiskit.visualization import plot_state_city\n",
"\n",
"plot_state_city(psi)\n",
"# Alternative: psi.draw(\"city\")"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "31c6b641-9447-46c9-aecc-5a5602bbd538",
"metadata": {
"tags": [
"id-tabs-hinton"
]
},
"outputs": [
{
"data": {
"text/plain": [
""
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from qiskit.visualization import plot_state_hinton\n",
"\n",
"plot_state_hinton(psi)\n",
"# Alternative: psi.draw(\"hinton\")"
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "b7729b72-3597-4360-a731-180314abc849",
"metadata": {
"tags": [
"id-tabs-paulivec"
]
},
"outputs": [
{
"data": {
"text/plain": [
""
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from qiskit.visualization import plot_state_paulivec\n",
"\n",
"plot_state_paulivec(psi)\n",
"# Alternative: psi.draw(\"paulivec\")"
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "4a3da3f4-4ee6-4b2a-8d3c-215fc14eb3f9",
"metadata": {
"tags": [
"id-tabs-paulivec-2"
]
},
"outputs": [
{
"data": {
"text/plain": [
"SparsePauliOp(['II', 'IX', 'XY', 'YI', 'YX', 'YZ', 'ZI', 'ZX', 'ZZ'],\n",
" coeffs=[ 0.25 +0.j, 0.1767767+0.j, -0.1767767+0.j, -0.125 +0.j,\n",
" -0.1767767+0.j, 0.125 +0.j, 0.125 +0.j, 0.1767767+0.j,\n",
" 0.125 +0.j])"
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from qiskit.quantum_info import SparsePauliOp\n",
"\n",
"SparsePauliOp.from_operator(psi)"
]
},
{
"cell_type": "code",
"execution_count": 8,
"id": "aa034130-f9b6-4a2b-9dbf-20615bb15c6f",
"metadata": {
"tags": [
"id-tabs-qsphere"
]
},
"outputs": [
{
"data": {
"text/plain": [
""
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from qiskit.visualization import plot_state_qsphere\n",
"\n",
"plot_state_qsphere(psi)\n",
"# Alternative: psi.draw(\"qsphere\")"
]
},
{
"cell_type": "code",
"execution_count": 9,
"id": "0a097bb3-d6b7-488b-8951-fc53aa7eae57",
"metadata": {
"tags": [
"id-tabs-bloch"
]
},
"outputs": [
{
"data": {
"text/plain": [
""
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from qiskit.visualization import plot_bloch_multivector\n",
"\n",
"plot_bloch_multivector(psi)\n",
"# Alternative: psi.draw(\"bloch\")"
]
},
{
"cell_type": "markdown",
"id": "878769c0-c2ea-42c0-bb72-78c651bdba19",
"metadata": {},
"source": [
"## Options for state-plotting functions\n",
"\n",
"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**):\n",
"\n",
"* **title** (str): a string for the plot title, displayed at the top of the plot\n",
"* **figsize** (tuple): figure size in inches (width, height)\n",
"\n",
"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](/docs/api/qiskit/visualization) for more information.\n",
"\n"
]
},
{
"cell_type": "markdown",
"id": "d448035a-dfa0-42dc-bef8-aaf5742d818d",
"metadata": {},
"source": [
"## Next steps\n",
"\n",
"\n",
" * Need to refresh your quantum information knowledge? Check out the [Basics of quantum information](/learning/courses/basics-of-quantum-information) course on IBM Quantum Learning.\n",
" * Read the [contributing guidelines](https://github.com/Qiskit/qiskit/blob/main/CONTRIBUTING.md) if you want to contribute to the open-source Qiskit SDK.\n",
"\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"id": "a1b8767d",
"source": "© IBM Corp., 2017-2026"
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3"
}
},
"nbformat": 4,
"nbformat_minor": 4
}