# display_bloch_sphere

Source: https://docs.q-ctrl.com/references/qctrl-visualizer/qctrlvisualizer/display_bloch_sphere

```python
qctrlvisualizer.display_bloch_sphere(states, color=None, width=300, visualizer_js=None)
```

Display a trajectory on the Bloch sphere using state vectors as input.

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.

This function plots trajectories on the surface of the Bloch sphere if
you provide normalized state vectors. To display trajectories in the
interior of the sphere, provide non-normalized state vectors, or use
[display_bloch_sphere_from_density_matrices](https://docs.q-ctrl.com/references/qctrl-visualizer/qctrlvisualizer/display_bloch_sphere_from_density_matrices.html) or
[display_bloch_sphere_from_bloch_vectors](https://docs.q-ctrl.com/references/qctrl-visualizer/qctrlvisualizer/display_bloch_sphere_from_bloch_vectors.html).

### Parameters
* **states** (*np.ndarray*) – A trajectory of single-qubit states represented by state vectors.
  This array must have shape `[T,2]`, where `T` is the number of
  state vectors in the trajectory.
* **color** (*str* *or* *None* *,* *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](https://www.w3.org/TR/css-color-3/#colorunits). 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.

### SEE ALSO
[`display_bloch_sphere_from_bloch_vectors`](https://docs.q-ctrl.com/references/qctrl-visualizer/qctrlvisualizer/display_bloch_sphere_from_bloch_vectors.md#qctrlvisualizer.display_bloch_sphere_from_bloch_vectors), [`display_bloch_sphere_from_density_matrices`](https://docs.q-ctrl.com/references/qctrl-visualizer/qctrlvisualizer/display_bloch_sphere_from_density_matrices.md#qctrlvisualizer.display_bloch_sphere_from_density_matrices)

## Notes

This function represents the trajectory of single-qubit states as
points on the Bloch sphere. The points on the Bloch sphere have
spherical coordinates $(r, \theta, \phi)$, which (up to a global
phase) correspond to each state vector
$\left| \psi \right\rangle$ in the trajectory according to:

$$
\left| \psi \right\rangle = \sqrt{r} \cos(\theta/2)
\left| 0 \right\rangle + \sqrt{r} e^{i \phi} \sin(\theta/2)
\left| 1 \right\rangle.
$$

The Bloch sphere has unit radius. If the states that you provide are
not normalized, then $r \ne 1$ and you can draw trajectories
inside the Bloch sphere.

## Styling

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”.
