Matplotlib viewer#

Matplotlib Bloch spheres: static figures, animations, GIF and MP4 export, an entanglement timeline and the Q-sphere.

Examples

>>> from qiskit import QuantumCircuit
>>> from quantum_mind.viz import circuit_trajectory, animate_trajectory, plot_entanglement
>>> qc = QuantumCircuit(2); qc.h(0); qc.cx(0, 1)
>>> traj = circuit_trajectory(qc, steps=15)
>>> animate_trajectory(traj, save='bell.gif', rotate=0.5)
>>> plot_entanglement(traj).savefig('bell_timeline.png')

Classes

BlochSphere

One Bloch sphere on a Matplotlib 3D axis.

Functions

plot_bloch

Static figure with one sphere per qubit.

animate_trajectory

Animate a trajectory, one sphere per qubit.

plot_entanglement

Entanglement timeline of a circuit trajectory.

plot_qsphere

Q-sphere of a multi-qubit state, drawn by Qiskit's plot_state_qsphere.
class BlochSphere(ax=None, title='', theme='dark', figsize=(5, 5), elev=20, azim=35)[source]#

Bases: object

One Bloch sphere on a Matplotlib 3D axis.

Parameters:

  • ax (mpl_toolkits.mplot3d.Axes3D, optional) – Axis to draw on (a new figure by default).

  • title (str, optional) – Caption under the sphere.

  • theme (str or dict, optional) – 'dark' (default), 'light' or a custom theme.

  • figsize (tuple, optional) – Figure size for a new figure.

  • elev (float, optional) – Camera angles in degrees.

  • azim (float, optional) – Camera angles in degrees.

Examples

>>> b = BlochSphere(title='q0')
>>> b.add_vector([0, 1, 0])
>>> b.save('sphere.png')
add_vector(r, color=None, label=None, lw=3)[source]#

Arrow from the origin to a Bloch vector.

Parameters:

  • r (array_like) – (x, y, z).

  • color (str, optional) – Colour (next palette colour by default).

  • label (str, optional) – Legend label.

  • lw (float, optional) – Line width.

Returns:

tuple – (line, tip) artists, which animations update.

add_state(state, **kw)[source]#

Arrow for a qubit state.

Parameters:

  • state (array_like or Qiskit state) – 2-vector, 2 x 2 density matrix, Statevector or DensityMatrix.

  • **kw – Passed to add_vector().

Returns:

tuple

add_points(points, color=None, size=12, alpha=0.9)[source]#

Scatter points on or inside the sphere.

Parameters:

  • points (array_like) – Shape (n, 3).

  • color (str, optional)

  • size (float, optional)

  • alpha (float, optional)

Returns:

matplotlib artist

add_trajectory(points, color=None, lw=1.8, alpha=0.8)[source]#

Draw a path of Bloch vectors.

Parameters:

  • points (array_like) – Shape (n, 3).

  • color (str, optional)

  • lw (float, optional)

  • alpha (float, optional)

Returns:

matplotlib line

show()[source]#

Show the figure.

save(path, dpi=150)[source]#

Save the figure.

Parameters:

  • path (str) – File name (format from the extension).

  • dpi (int, optional)

plot_bloch(vectors, names=None, theme='dark', title=None, size=3.6)[source]#

Static figure with one sphere per qubit.

Parameters:

  • vectors (array_like or state) – Bloch vectors (qubits, 3), or a state vector, density matrix or Qiskit state.

  • names (list of str, optional) – Qubit names.

  • theme (str or dict, optional)

  • title (str, optional)

  • size (float, optional) – Size per sphere in inches.

Returns:

animate_trajectory(traj, theme='dark', interval=40, trail=True, save=None, fps=25, size=3.6, rotate=0.0, title=None, dpi=90)[source]#

Animate a trajectory, one sphere per qubit.

Parameters:

  • traj (Trajectory or array_like) – Trajectory, or Bloch vectors (frames, qubits, 3).

  • theme (str or dict, optional)

  • interval (int, optional) – Milliseconds between frames on screen.

  • trail (bool, optional) – Draw the path followed so far.

  • save (str, optional) – Path ending in .gif (Pillow) or .mp4 (ffmpeg).

  • fps (int, optional) – Frames per second of the saved file.

  • size (float, optional) – Size per sphere in inches.

  • rotate (float, optional) – Camera rotation per frame, in degrees.

  • title (str, optional)

  • dpi (int, optional) – Resolution of the saved file.

Returns:

matplotlib.animation.FuncAnimation

plot_entanglement(traj, pairs=None, theme='dark', size=(8, 3.2))[source]#

Entanglement timeline of a circuit trajectory.

Plots the Bloch-vector length of every qubit (1 = not entangled with the others, for a pure global state) and the concurrence of qubit pairs (0 = separable, 1 = maximally entangled), with the gate labels on the x axis.

Parameters:

  • traj (Trajectory) – Circuit trajectory (with stored states, for the concurrence).

  • pairs (list of tuple, optional) – Qubit pairs (default: up to six pairs).

  • theme (str or dict, optional)

  • size (tuple, optional) – Figure size.

Returns:

matplotlib.figure.Figure

plot_qsphere(state, **kw)[source]#

Q-sphere of a multi-qubit state, drawn by Qiskit’s plot_state_qsphere.

Basis states are placed by Hamming weight, with amplitude as size and phase as colour.

Parameters:
Returns:

matplotlib.figure.Figure