Bloch Visualization

[sagnikpal2004]

Checklist

• Please read Contributing to Quantum Toolbox in Julia.
• Any code changes were done in a way that does not break public API.
• Appropriate tests were added and tested locally by running: make test.
• Any code changes should be julia formatted by running: make format.
• All documents (in docs/ folder) related to code changes were updated and able to build locally by running: make docs.
• (If necessary) the CHANGELOG.md should be updated (regarding to the code changes) and built by running: make changelog.

Description

This PR introduces a complete Bloch sphere visualization framework implemented using Makie.jl, ported from qutip but optimized for Julia. The Bloch type is designed to display and interactively visualize qubit states, including support for vectors, points, annotations, and more, with full customization.

Related issues or PRs

Closes #461

Features

Core Type

• Bloch struct that holds figure, scene, and all style/data attributes.
• Configurable view angles, background toggle, and figure size.

Plotting Capabilities

• add_points! to add raw (x, y, z) points.
• add_states! to convert Qobj qubit states into Bloch coordinates and plot as either vectors or points.
• add_vectors! to add custom 3D directional vectors.
• add_annotation! to label specific positions with text or LaTeX (via L-strings).
• add_line! and add_arc! to draw between points/states on the sphere.

Customization

• Set label conventions ("original", "xyz", "polarization jones", etc.) using set_label_convention!.
• Adjust colors, font sizes, sphere/frame styles, and transparency.

Export & Display

• Support for Base.show in both image/png and image/svg+xml mimetypes (IPython/Jupyter compatibility).
• save method to export the figure to disk with optional directory and DPI configuration.
• show! for interactive viewing via display.

Code Preview

• Example 1

using QuantumToolbox
using GLMakie

b = Bloch()
add_states!(b, Qobj([1, 0]), kind="vector", colors="red")
add_states!(b, Qobj([0, 1]), kind="vector", colors="blue")
add_states!(b, Qobj([1/√2, -1/√2]), kind="vector", colors="green")
add_annotation!(b, (-1.1, 0, 0), "|-⟩")
show!(b)

• Example 2

using QuantumToolbox
using GLMakie

b = Bloch()

add_points!(b, [0.0, 0.0, 1])
add_points!(b, [0.0, 0.0, -1])
add_points!(b, [
    [0.41, 0.2, 1.0], 
    [0.41, 0.3, -1.0], 
    [0.41, -1.0, 1.0], 
    [0.41, -1.0, -1.0]
], meth="l")

add_states!(b, rand_ket(2))
add_vectors!(b, [0, 0, 1]; alpha=0.4)

add_line!(b, rand_ket(2), rand_ket(2))
add_arc!(b, rand_ket(2), rand_ket(2))

show!(b)

API Summary

Bloch, set_label_convention!, clear!, add_points!,
add_states!, add_vectors!, add_annotation!,
add_line!, add_arc!, render!, show!

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 274 lines in your changes missing coverage. Please review.

Project coverage is 14.48%. Comparing base (a1d1627) to head (8805dc6).
Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
src/bloch.jl	0.00%	274 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (a1d1627) and HEAD (8805dc6). Click for more details.

HEAD has 8 uploads less than BASE

Flag	BASE (a1d1627)	HEAD (8805dc6)
	10	2

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #478       +/-   ##
===========================================
- Coverage   94.08%   14.48%   -79.61%     
===========================================
  Files          49       50        +1     
  Lines        3042     3273      +231     
===========================================
- Hits         2862      474     -2388     
- Misses        180     2799     +2619     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[albertomercurio]

Hi @sagnikpal2004, thanks for contributing.

Be aware that there is already another PR similar to this, already in an advanced stage.

Anyhow, you added Makie as a direct dependency, but this is not possible. Makie has to be as just an extension.

Moreover, could you show all the examples shown in the qutip documentation?

https://qutip.readthedocs.io/en/stable/guide/guide-bloch.html

[albertomercurio]

I regret to inform you that #472 has been accepted and merged. I will close this PR.