fix Bloch docstrings and improve visualization of the sphere

Author: ytdHuang

CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Introduce `Lanczos` solver for `spectrum`. ([#476])
 - Add Bloch-Redfield master equation solver. ([#473])
-- Implement Bloch Sphere rendering and align style with qutip. ([#472], [#480], [#485])
+- Implement Bloch Sphere rendering and align style with qutip. ([#472], [#480], [#485], [#487])
 - Add `Base.copy` method for `AbstractQuantumObject`. ([#486])
 
 ## [v0.31.1]
@@ -239,3 +239,4 @@ Release date: 2024-11-13
 [#480]: https://github.com/qutip/QuantumToolbox.jl/issues/480
 [#485]: https://github.com/qutip/QuantumToolbox.jl/issues/485
 [#486]: https://github.com/qutip/QuantumToolbox.jl/issues/486
+[#487]: https://github.com/qutip/QuantumToolbox.jl/issues/487

docs/src/users_guide/plotting_the_bloch_sphere.md

@@ -17,6 +17,9 @@ In [`QuantumToolbox`](https://qutip.org/QuantumToolbox.jl/), this can be done us
 
 In [`QuantumToolbox`](https://qutip.org/QuantumToolbox.jl/), creating a [`Bloch`](@ref) sphere is accomplished by calling either:
 
+!!! note "Import plotting libraries"
+    Remember to import plotting libraries first. Here, we demonstrate the functionalities with [`CairoMakie.jl`](https://docs.makie.org/stable/explanations/backends/cairomakie.html).
+
 ```@example Bloch_sphere_rendering
 b = Bloch()
 ```
@@ -172,7 +175,7 @@ At the end of the last section we saw that the colors and marker shapes of the d
 | `b.lines` | Lines to draw on the sphere (points, style, properties) | `Vector{Tuple{Vector{Vector{Float64}},String}}()` (empty) |
 | `b.arcs` | Arcs to draw on the sphere | `Vector{Vector{Vector{Float64}}}()` (empty) |
 | `b.font_color` | Color of axis labels and text | `"black"` |
-| `b.font_size` | Font size for labels | `15` |
+| `b.font_size` | Font size for labels | `20` |
 | `b.frame_alpha` | Transparency of the frame background | `0.1` |
 | `b.frame_color` | Background color of the frame | `"gray"` |
 | `b.frame_limit` | Axis limits for the 3D frame (symmetric around origin) | `1.2` |

ext/QuantumToolboxMakieExt.jl

@@ -34,8 +34,6 @@ import Makie:
     update_cam!,
     cam3d!
 
-import Makie.GeometryBasics: Tessellation
-
 @doc raw"""
     plot_wigner(
         library::Val{:Makie},
@@ -339,10 +337,7 @@ Render the Bloch sphere visualization from the given [`Bloch`](@ref) object `b`.
 # Arguments
 
 - `b::Bloch`: The Bloch sphere object containing states, vectors, and settings to visualize.
-- `location`: Specifies where to display or save the rendered figure.
-  - If `nothing` (default), the figure is displayed interactively.
-  - If a file path (String), the figure is saved to the specified location.
-  - Other values depend on backend support.
+- `location::Union{GridPosition,Nothing}`: The location of the plot in the layout. If `nothing`, the plot is created in a new figure. Default is `nothing`.
 
 # Returns
 
@@ -351,13 +346,14 @@ Render the Bloch sphere visualization from the given [`Bloch`](@ref) object `b`.
 function QuantumToolbox.render(b::Bloch; location = nothing)
     fig, lscene = _setup_bloch_plot!(b, location)
     _draw_bloch_sphere!(b, lscene)
-    _draw_reference_circles!(b, lscene)
-    _draw_axes!(b, lscene)
+    _add_labels!(b, lscene)
+
+    # plot data fields in Bloch
     _plot_points!(b, lscene)
     _plot_lines!(b, lscene)
     _plot_arcs!(b, lscene)
     _plot_vectors!(b, lscene)
-    _add_labels!(b, lscene)
+
     return fig, lscene
 end
 
@@ -383,15 +379,15 @@ function _setup_bloch_plot!(b::Bloch, location)
     cam3d!(lscene.scene, center = false)
     cam = cameracontrols(lscene)
     cam.fov[] = 12 # Set field of view to 12 degrees
-    dist = 12 # Set distance from the camera to the Bloch sphere
+    dist = 12      # Set distance from the camera to the Bloch sphere
     update_cam!(lscene.scene, cam, deg2rad(b.view[1]), deg2rad(b.view[2]), dist)
     return fig, lscene
 end
 
 raw"""
-    _draw_bloch_sphere!(b, lscene)
+    _draw_bloch_sphere!(b::Bloch, lscene)
 
-Draw the translucent sphere representing the Bloch sphere surface.
+Draw the translucent sphere, axes, and reference circles representing the Bloch sphere surface.
 """
 function _draw_bloch_sphere!(b::Bloch, lscene)
     radius = 1.0f0
@@ -405,69 +401,114 @@ function _draw_bloch_sphere!(b::Bloch, lscene)
         transparency = true,
         rasterize = 3,
     )
-    θ_vals = range(0, π, 5)[1:(end-1)]
+
+    # X, Y, and Z axes
+    axes = [
+        [Point3f(1.0, 0, 0), Point3f(-1.0, 0, 0)],  # X-axis
+        [Point3f(0, 1.0, 0), Point3f(0, -1.0, 0)],  # Y-axis
+        [Point3f(0, 0, 1.0), Point3f(0, 0, -1.0)],  # Z-axis
+    ]
+    for points in axes
+        lines!(lscene, points; color = b.frame_color)
+    end
+
+    # highlight circles for XY and XZ planes
+    φ = range(0, 2π, length = 100)
+    lines!(lscene, [Point3f(cos(φi), sin(φi), 0) for φi in φ]; color = b.frame_color, linewidth = 1.0) # XY
+    lines!(lscene, [Point3f(cos(φi), 0, sin(φi)) for φi in φ]; color = b.frame_color, linewidth = 1.0) # XZ
+
+    # other curves of longitude (with polar angle φ and azimuthal angle θ)
     φ_curve = range(0, 2π, 600)
+    θ_vals = [1, 2, 3] * π / 4
     for θi in θ_vals
         x_line = radius * sin.(φ_curve) .* cos(θi)
         y_line = radius * sin.(φ_curve) .* sin(θi)
         z_line = radius * cos.(φ_curve)
         lines!(lscene, x_line, y_line, z_line; color = b.frame_color, alpha = b.frame_alpha)
     end
-    φ_vals = range(0, π, 6)
+
+    # other curves of latitude (with polar angle φ and azimuthal angle θ)
+    φ_vals = [1, 3] * π / 4  # missing `2` because XY plane has already be handled above
     θ_curve = range(0, 2π, 600)
     for ϕ in φ_vals
         x_ring = radius * sin(ϕ) .* cos.(θ_curve)
         y_ring = radius * sin(ϕ) .* sin.(θ_curve)
         z_ring = fill(radius * cos(ϕ), length(θ_curve))
         lines!(lscene, x_ring, y_ring, z_ring; color = b.frame_color, alpha = b.frame_alpha)
     end
+    return nothing
 end
 
 raw"""
-    _draw_reference_circles!(b::Bloch, lscene)
+    _add_labels!(b::Bloch, lscene)
 
-Draw the three great circles `(XY, XZ planes)` on the Bloch sphere.
+Add axis labels and state labels to the Bloch sphere.
 
 # Arguments
-- `b::Bloch`: Bloch sphere object containing frame color
-- `lscene`: Makie LScene object for drawing
+- `lscene`: LScene object for text placement
 
-Adds faint circular guidelines representing the three principal planes.
+Positions standard labels `(x, y, |0⟩, |1⟩)` at appropriate locations.
 """
-function _draw_reference_circles!(b::Bloch, lscene)
-    wire_color = b.frame_color
-    φ = range(0, 2π, length = 100)
-    # XY, XZ circles
-    circles = [
-        [Point3f(cos(φi), sin(φi), 0) for φi in φ],  # XY
-        [Point3f(cos(φi), 0, sin(φi)) for φi in φ],  # XZ
-    ]
-    for circle in circles
-        lines!(lscene, circle; color = wire_color, linewidth = 1.0)
-    end
-end
-
-raw"""
-    _draw_axes!(b::Bloch, lscene)
-
-Draw the three principal axes `(x, y, z)` of the Bloch sphere.
+function _add_labels!(b::Bloch, lscene)
+    length(b.xlabel) == 2 || throw(ArgumentError("The length of `Bloch.xlabel` must be 2."))
+    length(b.ylabel) == 2 || throw(ArgumentError("The length of `Bloch.ylabel` must be 2."))
+    length(b.zlabel) == 2 || throw(ArgumentError("The length of `Bloch.zlabel` must be 2."))
+    length(b.xlpos) == 2 || throw(ArgumentError("The length of `Bloch.xlpos` must be 2."))
+    length(b.ylpos) == 2 || throw(ArgumentError("The length of `Bloch.ylpos` must be 2."))
+    length(b.zlpos) == 2 || throw(ArgumentError("The length of `Bloch.zlpos` must be 2."))
 
-# Arguments
-- `b::Bloch`: Bloch sphere object containing axis color
-- `lscene`: Makie LScene object for drawing
+    label_color = parse(RGBf, b.font_color)
+    label_size = b.font_size
 
-Creates visible axis lines extending slightly beyond the unit sphere.
-"""
-function _draw_axes!(b::Bloch, lscene)
-    axis_color = b.frame_color
-    axes = [
-        [Point3f(1.0, 0, 0), Point3f(-1.0, 0, 0)],  # X-axis
-        [Point3f(0, 1.0, 0), Point3f(0, -1.0, 0)],  # Y-axis
-        [Point3f(0, 0, 1.0), Point3f(0, 0, -1.0)],  # Z-axis
-    ]
-    for points in axes
-        lines!(lscene, points; color = axis_color)
-    end
+    (b.xlabel[1] == "") || text!(
+        lscene,
+        b.xlabel[1],
+        position = Point3f(b.xlpos[1], 0, 0),
+        color = label_color,
+        fontsize = label_size,
+        align = (:center, :center),
+    )
+    (b.xlabel[2] == "") || text!(
+        lscene,
+        b.xlabel[2],
+        position = Point3f(b.xlpos[2], 0, 0),
+        color = label_color,
+        fontsize = label_size,
+        align = (:center, :center),
+    )
+    (b.ylabel[1] == "") || text!(
+        lscene,
+        b.ylabel[1],
+        position = Point3f(0, b.ylpos[1], 0),
+        color = label_color,
+        fontsize = label_size,
+        align = (:center, :center),
+    )
+    (b.ylabel[2] == "") || text!(
+        lscene,
+        b.ylabel[2],
+        position = Point3f(0, b.ylpos[2], 0),
+        color = label_color,
+        fontsize = label_size,
+        align = (:center, :center),
+    )
+    (b.zlabel[1] == "") || text!(
+        lscene,
+        b.zlabel[1],
+        position = Point3f(0, 0, b.zlpos[1]),
+        color = label_color,
+        fontsize = label_size,
+        align = (:center, :center),
+    )
+    (b.zlabel[2] == "") || text!(
+        lscene,
+        b.zlabel[2],
+        position = Point3f(0, 0, b.zlpos[2]),
+        color = label_color,
+        fontsize = label_size,
+        align = (:center, :center),
+    )
+    return nothing
 end
 
 raw"""
@@ -540,6 +581,7 @@ function _plot_points!(b::Bloch, lscene)
             lines!(lscene, xs, ys, zs; color = c, linewidth = 2.0, transparency = alpha < 1.0, alpha = alpha)
         end
     end
+    return nothing
 end
 
 raw"""
@@ -571,6 +613,7 @@ function _plot_lines!(b::Bloch, lscene)
         end
         lines!(lscene, x, y, z; color = color, linewidth = 1.0, linestyle = linestyle)
     end
+    return nothing
 end
 
 raw"""
@@ -599,6 +642,7 @@ function _plot_arcs!(b::Bloch, lscene)
         arc_points = [Point3f((v1 * cos(t) + cross(n, v1) * sin(t))) for t in t_range]
         lines!(lscene, arc_points; color = RGBAf(0.8, 0.4, 0.1, 0.9), linewidth = 2.0, linestyle = :solid)
     end
+    return nothing
 end
 
 raw"""
@@ -633,77 +677,6 @@ function _plot_vectors!(b::Bloch, lscene)
             rasterize = 3,
         )
     end
-end
-
-raw"""
-    _add_labels!(lscene)
-
-Add axis labels and state labels to the Bloch sphere.
-
-# Arguments
-- `lscene`: LScene object for text placement
-
-Positions standard labels `(x, y, |0⟩, |1⟩)` at appropriate locations.
-"""
-function _add_labels!(b::Bloch, lscene)
-    length(b.xlabel) == 2 || throw(ArgumentError("The length of `Bloch.xlabel` must be 2."))
-    length(b.ylabel) == 2 || throw(ArgumentError("The length of `Bloch.ylabel` must be 2."))
-    length(b.zlabel) == 2 || throw(ArgumentError("The length of `Bloch.zlabel` must be 2."))
-    length(b.xlpos) == 2 || throw(ArgumentError("The length of `Bloch.xlpos` must be 2."))
-    length(b.ylpos) == 2 || throw(ArgumentError("The length of `Bloch.ylpos` must be 2."))
-    length(b.zlpos) == 2 || throw(ArgumentError("The length of `Bloch.zlpos` must be 2."))
-
-    label_color = parse(RGBf, b.font_color)
-    label_size = b.font_size
-
-    (b.xlabel[1] == "") || text!(
-        lscene,
-        b.xlabel[1],
-        position = Point3f(b.xlpos[1], 0, 0),
-        color = label_color,
-        fontsize = label_size,
-        align = (:center, :center),
-    )
-    (b.xlabel[2] == "") || text!(
-        lscene,
-        b.xlabel[2],
-        position = Point3f(b.xlpos[2], 0, 0),
-        color = label_color,
-        fontsize = label_size,
-        align = (:center, :center),
-    )
-    (b.ylabel[1] == "") || text!(
-        lscene,
-        b.ylabel[1],
-        position = Point3f(0, b.ylpos[1], 0),
-        color = label_color,
-        fontsize = label_size,
-        align = (:center, :center),
-    )
-    (b.ylabel[2] == "") || text!(
-        lscene,
-        b.ylabel[2],
-        position = Point3f(0, b.ylpos[2], 0),
-        color = label_color,
-        fontsize = label_size,
-        align = (:center, :center),
-    )
-    (b.zlabel[1] == "") || text!(
-        lscene,
-        b.zlabel[1],
-        position = Point3f(0, 0, b.zlpos[1]),
-        color = label_color,
-        fontsize = label_size,
-        align = (:center, :center),
-    )
-    (b.zlabel[2] == "") || text!(
-        lscene,
-        b.zlabel[2],
-        position = Point3f(0, 0, b.zlpos[2]),
-        color = label_color,
-        fontsize = label_size,
-        align = (:center, :center),
-    )
     return nothing
 end
 

src/visualization.jl

@@ -80,7 +80,7 @@ A structure representing a Bloch sphere visualization for quantum states.
 ## Style properties
 
 - `font_color::String`: Color of axis labels and text
-- `font_size::Int`: Font size for labels. Default: `15`
+- `font_size::Int`: Font size for labels. Default: `20`
 - `frame_alpha::Float64`: Transparency of the wireframe
 - `frame_color::String`: Color of the wireframe
 
@@ -122,7 +122,7 @@ A structure representing a Bloch sphere visualization for quantum states.
     lines::Vector{Tuple{Vector{Vector{Float64}},String}} = Vector{Tuple{Vector{Vector{Float64}},String}}()
     arcs::Vector{Vector{Vector{Float64}}} = Vector{Vector{Vector{Float64}}}()
     font_color::String = "black"
-    font_size::Int = 15
+    font_size::Int = 20
     frame_alpha::Float64 = 0.1
     frame_color::String = "gray"
     point_default_color::Vector{String} = ["blue", "red", "green", "#CC6600"]
@@ -515,10 +515,7 @@ Render the Bloch sphere visualization from the given [`Bloch`](@ref) object `b`.
 # Arguments
 
 - `b::Bloch`: The Bloch sphere object containing states, vectors, and settings to visualize.
-- `location`: Specifies where to display or save the rendered figure.
-  - If `nothing` (default), the figure is displayed interactively.
-  - If a file path (String), the figure is saved to the specified location.
-  - Other values depend on backend support.
+- `location::Union{GridPosition,Nothing}`: The location of the plot in the layout. If `nothing`, the plot is created in a new figure. Default is `nothing`.
 
 # Returns