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 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): An optional Axes object to be used for the visualization output. If none is specified a new matplotlib.figure.Figure 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)

(Source code)

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)

(Source code)

You can save the figure to file either by passing the file name to filename kwarg or use matplotlib.figure.Figure.savefig 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)

(Source code)

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)

(Source code)

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)

(Source code)

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)

(Source code)

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.
DefaultStyle()	Creates a Default Style dictionary

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.

Pulse Visualizations

pulse_drawer(program[, style, backend, ...])	Generate visualization data for pulse programs.
IQXStandard(**kwargs)	Standard pulse stylesheet.
IQXSimple(**kwargs)	Simple pulse stylesheet without channel notation.
IQXDebugging(**kwargs)	Pulse stylesheet for pulse programmers.

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

exception qiskit.visualization.VisualizationError(*message)

For visualization specific errors.

Set the error message.