Skip to main contentIBM Quantum Documentation

Visualizations

qiskit.visualization

The visualization module contain functions that visualizes measurement outcome counts, quantum states, circuits, pulses, devices and more.

To use visualization functions, you are required to install visualization optionals to your development environment:

pip install 'qiskit[visualization]'

Common Keyword Arguments

Many of the figures created by visualization functions in this module are created by Matplotlib(opens in a new tab) and accept a subset of the following common arguments. Consult the individual documentation for exact details.

  • title (str): a text string to use for the plot title.
  • legend (list): a list of strings to use for labels of the data.
  • figsize (tuple): figure size in inches .
  • color (list): a list of strings for plotting.
  • ax (matplotlib.axes.Axes(opens in a new tab)): An optional Axes object to be used for the visualization output. If none is specified a new matplotlib.figure.Figure(opens in a new tab) will be created and used. Additionally, if specified there will be no returned Figure since it is redundant.
  • filename (str): file path to save image to.

The following example demonstrates the common usage of these arguments:

from qiskit.visualization import plot_histogram
 
counts1 = {'00': 499, '11': 501}
counts2 = {'00': 511, '11': 489}
 
data = [counts1, counts2]
plot_histogram(data)
../_images/visualization-1.png

You can specify legend, title, figsize and color by passing to the kwargs.

from qiskit.visualization import plot_histogram
 
counts1 = {'00': 499, '11': 501}
counts2 = {'00': 511, '11': 489}
data = [counts1, counts2]
 
legend = ['First execution', 'Second execution']
title = 'New histogram'
figsize = (10,10)
color=['crimson','midnightblue']
plot_histogram(data, legend=legend, title=title, figsize=figsize, color=color)
../_images/visualization-2.png

You can save the figure to file either by passing the file name to filename kwarg or use matplotlib.figure.Figure.savefig(opens in a new tab) method.

plot_histogram(data, filename='new_hist.png')
 
hist = plot_histogram(data)
hist.savefig('new_hist.png')

Counts Visualizations

This section contains functions that visualize measurement outcome counts.

plot_histogram(data[, figsize, color, ...])Plot a histogram of input counts data.

Example Usage

Here is an example of using plot_histogram() to visualize measurement outcome counts:

from qiskit.visualization import plot_histogram
 
counts = {"00": 501, "11": 499}
plot_histogram(counts)
../_images/visualization-3.png

The data can be a dictionary with bit string as key and counts as value, or more commonly a Counts object obtained from get_counts().


Distribution Visualizations

This section contains functions that visualize sampled distributions.

plot_distribution(data[, figsize, color, ...])Plot a distribution from input sampled data.

State Visualizations

This section contains functions that visualize quantum states.

plot_bloch_vector(bloch[, title, ax, ...])Plot the Bloch sphere.
plot_bloch_multivector(state[, title, ...])Plot a Bloch sphere for each qubit.
plot_state_city(state[, title, figsize, ...])Plot the cityscape of quantum state.
plot_state_hinton(state[, title, figsize, ...])Plot a hinton diagram for the density matrix of a quantum state.
plot_state_paulivec(state[, title, figsize, ...])Plot the Pauli-vector representation of a quantum state as bar graph.
plot_state_qsphere(state[, figsize, ax, ...])Plot the qsphere representation of a quantum state.

Example Usage

Here is an example of using plot_state_city() to visualize a quantum state:

from qiskit.visualization import plot_state_city
 
state = [[ 0.75  , 0.433j],
         [-0.433j, 0.25  ]]
plot_state_city(state)
../_images/visualization-4.png

The state can be array-like list of lists, numpy.array, or more commonly Statevector or DensityMatrix objects obtained from a QuantumCircuit:

from qiskit import QuantumCircuit
from qiskit.quantum_info import Statevector
from qiskit.visualization import plot_state_city
 
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0,1)
 
# plot using a Statevector
state = Statevector(qc)
plot_state_city(state)
../_images/visualization-5.png
from qiskit import QuantumCircuit
from qiskit.quantum_info import DensityMatrix
from qiskit.visualization import plot_state_city
 
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0,1)
 
# plot using a DensityMatrix
state = DensityMatrix(qc)
plot_state_city(state)
../_images/visualization-6.png

You can find code examples for each visualization functions on the individual function API page.


Device Visualizations

plot_gate_map(backend[, figsize, ...])Plots the gate map of a device.
plot_error_map(backend[, figsize, ...])Plots the error map of a given backend.
plot_circuit_layout(circuit, backend[, ...])Plot the layout of a circuit transpiled for a given target backend.
plot_coupling_map(num_qubits, ...[, ...])Plots an arbitrary coupling map of qubits (embedded in a plane).

Circuit Visualizations

circuit_drawer(circuit[, scale, filename, ...])Draw the quantum circuit.

DAG Visualizations

dag_drawer(dag[, scale, filename, style])Plot the directed acyclic graph (dag) to represent operation dependencies in a quantum circuit.

Pass Manager Visualizations

pass_manager_drawer(pass_manager[, ...])Draws the pass manager.

Timeline Visualizations

timeline_drawer(program[, style, ...])Generate visualization data for scheduled circuit programs.

Single Qubit State Transition Visualizations

visualize_transition(circuit[, trace, ...])Creates animation showing transitions between states of a single qubit by applying quantum gates.

Array/Matrix Visualizations

array_to_latex(array[, precision, prefix, ...])Latex representation of a complex numpy array (with dimension 1 or 2)

Exceptions

VisualizationError

qiskit.visualization.VisualizationError(*message) GitHub(opens in a new tab)

For visualization specific errors.

Set the error message.

Was this page helpful?