qctrlvisualizer.display_bloch_sphere_from_bloch_vectors(bloch_vectors, color=None, width=300, visualizer_js=None)

Display a Bloch sphere with an animation of the Bloch vectors.

This function requires IPython, and you must run it from a Jupyter notebook. By default, it requires an Internet connection to fetch the JavaScript library for the Bloch sphere visualizer, but you can also use it offline by making a backup copy of the JavaScript file in your local filesystem.


  • bloch_vectors (np.ndarray) – A trajectory of Bloch vectors (that is, points either on or inside the Bloch sphere) given in Cartesian coordinates. This array must have shape [T,3], where T is the number of vectors in the trajectory.
  • color (str , optional) – A string identifying the color of the trajectory. The string must be a color value accepted by CSS, such as a hexadecimal code like “#00FF00” or a color name like “green”. The exact types of values accepted might depend on your browser, but you can find an official list of color values as part of the CSS standard. If you don’t pass a string, the default behavior is to use the color value “#EB6467”.
  • width (int , optional) – The width of the Bloch sphere, in pixels. Its height has the same value as the width. Defaults to 300 pixels.
  • visualizer_js (str or None , optional) – A string with the location of the JavaScript library for the Bloch sphere visualizer. It can be a URL or a path to a local file. If you don’t pass a string, the function uses the default online version of the Q-CTRL Visualizer JavaScript package.


QctrlArgumentsValueError – If bloch_vectors is of complex type.


display_bloch_sphere, display_bloch_sphere_from_density_matrices


The Bloch vector b\mathbf{b} is a 3D real vector that represents a point either on or inside the Bloch sphere. It is equivalent to a single-qubit state represented by a density matrix ρ\rho

ρ=12I+12(bxσx+byσy+bzσz), \rho = \frac{1}{2} I + \frac{1}{2} \left( b_x \sigma_x + b_y \sigma_y + b_z \sigma_z \right),

where II is the 2×22 \times 2 identity matrix, and bxb_x, byb_y, and bzb_z

For points on the surface of the Bloch sphere (that is, when the norm of the vector has value 1), the Bloch vector represents a pure state. In this case, if you write the Bloch vector in terms of the spherical coordinates (θ,ϕ)(\theta, \phi), such that bx=sinθcosϕb_x = \sin\theta \cos\phi, by=sinθsinϕb_y = \sin\theta \sin\phi, and bz=cosθb_z = \cos \theta

ψ=cos(θ/2)0+eiϕsin(θ/2)1. \left| \psi \right\rangle = \cos(\theta/2) \left| 0 \right\rangle + e^{i \phi} \sin(\theta/2) \left| 1 \right\rangle.


This function displays HTML and JavaScript in your Jupyter notebook. It creates four HTML elements that you can style by defining the following CSS classes:

qctrlvisualizer : CSS class for the outer <div> that contains the Bloch sphere visualization, progress bar, and button. The div has inline styles display:flex, flex-direction:column, and align-items:center, so if you want to use different values for these properties you must either strip them out or use the !important rule when defining your qctrlvisualizer class.

qctrlvisualizer-wrapper : CSS class for the <div> that contains the Bloch sphere visualization. The div has inline styles margin:0.5rem 0, width, and height (based on the width you pass).

qctrlvisualizer-progress-bar : CSS class for the range <input> representing the progress bar. The input has inline style margin:0.5rem 0.

qctrlvisualizer-button : CSS class for the <button> representing the play/pause/replay button. The button has inline style margin:0.5rem 0.

qctrlvisualizer-button-play : CSS class for the <button> when the button text is “Play”.

qctrlvisualizer-button-pause : CSS class for the <button> when the button text is “Pause”.

qctrlvisualizer-button-replay : CSS class for the <button> when the button text is “Replay”.

Was this useful?