Makie bloch sphere extension by Aniket-umass · Pull Request #216 · qojulia/QuantumOpticsBase.jl

Aniket-umass · 2026-02-02T19:53:40Z

Some rendering examples:
Arbitrary:

Spindown:

Spinup:

Adds a Bloch sphere visualization for pure qubit states (Ket) via a Makie extension. The extension loads automatically when the user loads any Makie backend (CairoMakie or GLMakie) — no extra dependencies are added to the base package.

How it works
A pure qubit state |ψ⟩ = α|0⟩ + β|1⟩ is mapped to a point on the unit sphere via the Pauli expectation values: x = 2Re(ᾱβ), y = 2Im(ᾱβ), z = |α|² − |β|². The arrow points to the state on the sphere surface.
Customizable attributes

arrowcolor (default :red) — color of the state vector arrow
spherecolor (default :lightblue) — color of the sphere surface
spherealpha (default 0.15) — transparency of the sphere
showwireframe (default true) — show equator and meridian circles
showaxes (default true) — show dashed x/y/z axis lines
showlabels (default true) — show pole labels |0⟩ |1⟩ |+⟩ |-⟩ |+i⟩ |-i⟩
labelsize (default 18) — font size for pole labels

Files changed
ext/QuantumOpticsBaseMakieExt.jl — Makie recipe and blochsphere convenience constructor
src/visualization.jl — docstring and function stub for blochsphere
src/QuantumOpticsBase.jl — export and include for visualization.jl
Project.toml — Makie added as weak dependency
test/test_plotting.jl — tests using @testitem / TestItemRunner

Krastanov

Thanks, this is a good start!

Check the comments I left in.

A few other things:

this new functionality needs tests (check PBCCompiler.jl for an example of how to structure the tests)
and it needs docs
for ease of review, it would be helpful to post in the comments what a rendering looks like so we can discuss it before a full in-depth review.

Krastanov · 2026-02-02T20:32:45Z

You seem to have included some files from your local dev environment -- these should be removed

does not seem to be resolved

Krastanov · 2026-02-04T20:12:01Z

include("ext/QuantumOpticsBaseMakieExt.jl")

You should not include extensions manually. They are supposed to be loaded when the library is imported together with the weakdeps for the extension. Check out the details in the Pkg.jl manual.

Krastanov

looks like it is on a good track

could you address comments, resolve the merge conflict, verify that tests actually pass in CI, and post a few example plots in the PR description so that we know how it is being rendered

Krastanov · 2026-05-05T15:35:09Z

 uuid = "4f57444f-1401-5e15-980d-4471b28d5678"
 version = "0.5.9"
-
+ 


don't add "lint"

always check the file tab in the PR to look for unrelated changes that you have made by mistake

Krastanov · 2026-05-05T15:35:32Z

 FastExpm = "7868e603-8603-432e-a1a1-694bd70b01f2"
 FastGaussQuadrature = "442a2c76-b920-505d-bb47-c5924d526838"
 FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
+GeometryBasics = "5c1252a2-5f33-56bf-86c9-59e7332b4326"


you have added a new dependency -- this is supposed to be an extension

Krastanov · 2026-05-05T15:37:28Z

+error("Blochsphere visualization requires a Makie extension.\n" *
+      "Load QuantumOpticsBase together with CairoMakie or GLMakie.")


instead of creating a method for a function, just declare a function without any methods

function blochsphere end

Krastanov · 2026-05-05T15:38:20Z

                ChiMatrix, DenseChiMatrix, avg_gate_fidelity,
        SumBasis, directsum, ⊕, LazyDirectSum, getblock, setblock!,
-        qfunc, wigner, coherentspinstate, qfuncsu2, wignersu2
+        qfunc, wigner, coherentspinstate, qfuncsu2, wignersu2, blochsphere


if you are exporting a function, it should be documented

also, notice that the exports are organized, so maybe add a comment header for this new category of functions, e.g. visualizations

Krastanov · 2026-05-05T15:39:02Z

        #apply
                apply!

+                ###########  Bloch Sphere API Stub  ###########


do not make up new organization style comments

put this is a new file (notice that the exports above are organized by file) and include the file at the bottom

Krastanov · 2026-05-05T15:44:35Z

+    @testset "|0⟩ renders without error" begin
+        fig = blochsphere(spinup(b))
+        save("test_bloch_0.png", fig)
+        @test isfile("test_bloch_0.png")
+        rm("test_bloch_0.png")
+    end
+
+    @testset "|1⟩ renders without error" begin
+        fig = blochsphere(spindown(b))
+        save("test_bloch_1.png", fig)
+        @test isfile("test_bloch_1.png")
+        rm("test_bloch_1.png")
+    end
+
+    @testset "|+⟩ renders without error" begin
+        fig = blochsphere(normalize(spinup(b) + spindown(b)))
+        save("test_bloch_plus.png", fig)
+        @test isfile("test_bloch_plus.png")
+        rm("test_bloch_plus.png")
+    end
+
+    @testset "|-⟩ renders without error" begin
+        fig = blochsphere(normalize(spinup(b) - spindown(b)))
+        save("test_bloch_minus.png", fig)
+        @test isfile("test_bloch_minus.png")
+        rm("test_bloch_minus.png")
+    end
+
+    @testset "|+i⟩ renders without error" begin
+        fig = blochsphere(normalize(spinup(b) + im*spindown(b)))
+        save("test_bloch_plusi.png", fig)
+        @test isfile("test_bloch_plusi.png")
+        rm("test_bloch_plusi.png")
+    end
+
+    @testset "|-i⟩ renders without error" begin
+        fig = blochsphere(normalize(spinup(b) - im*spindown(b)))
+        save("test_bloch_minusi.png", fig)
+        @test isfile("test_bloch_minusi.png")
+        rm("test_bloch_minusi.png")
+    end


just pick one random arbitrary unnamed state and test for that -- these repeated tests do not really add much value to the test runner

Krastanov · 2026-05-05T15:47:04Z

+    lim = Float32(get(kwargs, :lim, 1.6))
+    Makie.limits!(ax, -lim, lim, -lim, lim, -lim, lim)
+    blochsphereplot!(ax, state; kwargs...)
+    return fig


return also the axis and the plot object

Krastanov · 2026-05-05T15:48:04Z

+        xzpanelvisible     = false,
+        yzpanelvisible     = false,
+    )
+    lim = Float32(get(kwargs, :lim, 1.6))


this seems like a non-standard name -- pick a name that matches the Makie API

Krastanov · 2026-05-05T15:49:16Z

+function Makie.convert_arguments(::Type{<:Makie.Plot{blochsphereplot}}, state::Ket)
+    return (state,)
+end


Why is this necessary?

Krastanov · 2026-05-05T15:51:42Z

+        arrowcolor    = :red,
+        spherecolor   = :lightblue,  
+        spherealpha   = 0.15,        
+        showwireframe = true,        
+        showaxes      = true,        
+        showlabels    = true,        
+        labelsize     = 18,
+        title         = "Bloch Sphere",
+        shaftradius   = 0.018,
+        tipradius     = 0.050,
+        tiplength     = 0.10,
+        lim           = 1.6,


lim does not seem like a standard name, verify it is correct

a bunch of these do not seem to be used (e.g. title) -- just remove them

…sion

…d/green/blue

Krastanov · 2026-05-18T15:40:56Z

+end
+
+
+function QuantumOpticsBase.blochsphere(state::Ket; limits=1.6, kwargs...)


The API here is a bit unidiomatic.

Let's focus first on having the default Makie recipe functions be in the QuantumOpticsBase namespace. See https://docs.makie.org/stable/explanations/recipes#Makie-Package-Extension

Then, after we have the default functions, we can provide an extra API that is not idiomatic to Makie that provides not just a "plot" but also "axis" manipulation.

see https://github.com/QuantumSavory/QuantumSavory.jl/blob/master/src/plots.jl, in particular registernetplot_axis

rename to blochsphereplot_axis as in: https://github.com/QuantumSavory/QuantumSavory.jl/blob/766f69c7f5e595328d46883fb3bd3f945e373b0d/ext/QuantumSavoryMakie/QuantumSavoryMakie.jl#L340-L348

Krastanov · 2026-05-18T15:47:34Z

 /docs/build/
 Manifest.toml
 .vscode
+~/.julia/


a tilda inside of a gitignore does not really make sense to me -- if you need it, you probably should reorganize how you have set up your work environment

Krastanov · 2026-05-18T15:56:45Z

Use error hints so that the user is told that they need to import a makie backend. See here https://github.com/QuantumSavory/QuantumSavory.jl/blob/766f69c7f5e595328d46883fb3bd3f945e373b0d/src/QuantumSavory.jl#L103

… blochsphere to blochsphereplot_axis, add Observable reactivity test

Aniket-umass added 2 commits February 2, 2026 12:14

Add Makie Bloch sphere extension using Ket and update Project.toml

27dc6dc

Add Makie Bloch sphere extension using Ket

52258f4

Krastanov requested changes Feb 2, 2026

View reviewed changes

Krastanov marked this pull request as draft February 2, 2026 20:39

Aniket-umass added 2 commits March 4, 2026 17:01

Made requested changes to Bloch sphere extension

041567b

Update Bloch sphere extension and add TestItemRunner tests

5cacd7e

Krastanov requested changes May 5, 2026

View reviewed changes

Aniket-umass added 9 commits May 5, 2026 12:22

Remove accidentally committed local dev Project.toml

acf1ca9

Add .gitignore to exclude local Julia dev paths

b4e919d

Merge remote-tracking branch 'origin/master' into makie-bloch-extension

214a214

Address all PR review comments

ac3a93c

Merge remote-tracking branch 'upstream/master' into makie-bloch-exten…

ea795c3

…sion

Resolve Project.toml merge conflict with upstream

f1c60fe

Update ext, test, and QuantumOpticsBase files with all review fixes

85d0a33

Fix export block and remove GeometryBasics from compat

b92a70d

Add explicit Makie import for CI compatibility

726c762

Aniket-umass marked this pull request as ready for review May 18, 2026 01:51

Aniket-umass added 3 commits May 17, 2026 22:13

fix: use AbstractPlot instead of Makie.Plot to avoid bare Makie import

70ebacd

fix: use AbstractPlot instead of Makie.Plot to avoid bare Makie import

2da4ae6

fix: extract limits kwarg explicitly, use c.r/g/b instead of Makie.re…

dd57194

…d/green/blue

Krastanov requested changes May 18, 2026

View reviewed changes

Aniket-umass added 2 commits May 19, 2026 22:28

refactor: put recipe functions in QuantumOpticsBase namespace, rename…

8dd3d5a

… blochsphere to blochsphereplot_axis, add Observable reactivity test

refactor: put recipe functions in QuantumOpticsBase namespace, rename…

7ff3bfa

… blochsphere to blochsphereplot_axis, add Observable reactivity test

		uuid = "4f57444f-1401-5e15-980d-4471b28d5678"
		version = "0.5.9"

		error("Blochsphere visualization requires a Makie extension.\n" *
		"Load QuantumOpticsBase together with CairoMakie or GLMakie.")

		end


		function QuantumOpticsBase.blochsphere(state::Ket; limits=1.6, kwargs...)

Conversation

Aniket-umass commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Krastanov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Krastanov commented Feb 4, 2026

Uh oh!

Krastanov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Krastanov commented May 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Aniket-umass commented Feb 2, 2026 •

edited

Loading