Visualize quantum statevectors using interactive Q-sphere (built with Plotly).
Inspired by IBM Qiskit's Q-sphere, this implementation provides beautiful, publication-quality interactive quantum state visualizations powered by Plotly.
- Interactive 3D visualization of n-qubit pure quantum states.
- Plotly-powered — zoom, rotate, and explore in your browser.
- Hoverable tooltips with bitstring, amplitude, probability, and phase.
- Customizable bitstring notations and colormaps for phase.
Clone the repository and install locally:
git clone https://github.com/crystaldot/plotly-qsphere.git
cd plotly-qsphere
pip install .from plotly_qsphere import plot_qsphere
import numpy as np
# Example: Bell state (|00⟩ + |11⟩) / √2
statevector = np.array([1/np.sqrt(2), 0, 0, 1/np.sqrt(2)], dtype=complex)
fig = plot_qsphere(statevector)
fig.show()Check out other example usage.
| Name | Type | Default | Description |
|---|---|---|---|
statevector |
np.ndarray |
required | Complex vector of size 2^n, representing the quantum state. |
prob_tol |
float |
1e-10 |
Ignore states with probability below this threshold. |
phase_offset |
bool |
True |
Recenter phases around the first non-zero amplitude. |
marker_size |
float |
100 |
Scale for marker sizes (∝ probability). |
notation |
str |
'CS' |
Bitstring display: 'CS', 'Physics', 'CS_GroupBits_n', 'Physics_GroupBits_n'. |
cscale |
str |
'hsv' |
Plotly color scale (e.g., 'hsv', 'icefire', 'edge'). |
show_in_degree |
bool |
False |
If True, display phase in degrees; else in radians. |
title |
str |
'Q-Sphere using Plotly' |
Title for the plot. |
Display_Height |
int |
600 |
Plot height in pixels. |
plotly.graph_objects.Figure
A Plotly Figure object representing the Q-sphere, ready for display or embedding.
This project is licensed under the BSD 3-Clause License.
See the LICENSE file for full license text.
Additional third-party acknowledgements are included in the NOTICE file.
- Inspired by IBM Qiskit's original Q-sphere visualizer.
- Built using open-source tools including NumPy and Plotly.