From cadc18a904d25a13367c04f0b39fc82ac5069eb5 Mon Sep 17 00:00:00 2001
From: Li-Xun Cai <157601901+TendonFFF@users.noreply.github.com>
Date: Thu, 31 Jul 2025 19:46:11 +0800
Subject: [PATCH 1/6] Bloch anime (#519)

Co-authored-by: cailixun <cailixun23@gmail.com>
---
 .../users_guide/plotting_the_bloch_sphere.md  | 61 ++++++++++++++++++-
 ext/QuantumToolboxMakieExt.jl                 | 40 +++++++++---
 2 files changed, 93 insertions(+), 8 deletions(-)

diff --git a/docs/src/users_guide/plotting_the_bloch_sphere.md b/docs/src/users_guide/plotting_the_bloch_sphere.md
index 8bb5facfe..50a6ca5d2 100644
--- a/docs/src/users_guide/plotting_the_bloch_sphere.md
+++ b/docs/src/users_guide/plotting_the_bloch_sphere.md
@@ -211,4 +211,63 @@ These properties can also be accessed via the `print` command:
 ```@example Bloch_sphere_rendering
 b = Bloch()
 print(b)
-```
\ No newline at end of file
+```
+
+## Animating with the Bloch sphere
+
+The [`Bloch`](@ref) structure was designed from the outset to generate animations. To animate a set of vectors or data points, the basic idea is: plot the data at time ``t_1``, save the sphere, clear the sphere, plot data at ``t_2``, and so on. The easiest way to animate data on the Bloch sphere is to use the `record` function provided by [`Makie.jl`](https://docs.makie.org/stable/). We will demonstrate this functionality with the following example: the decay of a qubit on the Bloch sphere.
+
+```@example Bloch_sphere_rendering
+# system parameters
+ω = 2π
+θ = 0.2π
+n_th = 0.5 # temperature
+γ1 = 0.5
+γ2 = 0.2
+
+# operators and the Hamiltonian
+sx = sigmax()
+sy = sigmay()
+sz = sigmaz()
+sm = sigmam()
+H = ω * (cos(θ) * sz + sin(θ) * sx)
+
+# collapse operators
+c_op_list = (
+    √(γ1 * (n_th + 1)) * sm,
+    √(γ1 * n_th) * sm',
+    √γ2 * sz
+)
+
+# solving evolution
+ψ0 = basis(2, 0)
+tlist = LinRange(0, 4, 250)
+sol = mesolve(H, ψ0, tlist, c_op_list, e_ops = (sx, sy, sz), progress_bar = Val(false))
+x = real(sol.expect[1,:])
+y = real(sol.expect[2,:])
+z = real(sol.expect[3,:])
+```
+
+To animate a set of vectors or data points, we use the `record` function provided by [`Makie.jl`](https://docs.makie.org/stable/):
+
+```@example Bloch_sphere_rendering
+b = Bloch()
+b.view = [50,30]
+
+fig, lscene = render(b)
+
+record(fig, "qubit_decay.mp4", eachindex(tlist), framerate = 20) do idx
+    clear!(b)
+    add_vectors!(b, [sin(θ), 0, cos(θ)])
+    add_points!(b, [x[1:idx], y[1:idx], z[1:idx]])
+    render(b, location = lscene)
+end
+nothing # hide
+```
+
+```@raw html
+<video autoplay loop muted playsinline controls src="./qubit_decay.mp4" />
+```
+
+!!! note
+    Here, we set the keyword argument `location = lscene` in the last `render` function to update the existing Bloch sphere without creating new `Figure` and `LScene`. This is efficient when drawing animations.
diff --git a/ext/QuantumToolboxMakieExt.jl b/ext/QuantumToolboxMakieExt.jl
index 4c6e8cc0b..0a135a500 100644
--- a/ext/QuantumToolboxMakieExt.jl
+++ b/ext/QuantumToolboxMakieExt.jl
@@ -337,14 +337,24 @@ 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::Union{GridPosition,Nothing}`: The location of the plot in the layout. If `nothing`, the plot is created in a new figure. Default is `nothing`.
+- `location::Union{GridPosition,LScene,Nothing}`: The location of the plot in the layout or `Makie.LScene`
+
 
 # Returns
 
 - A tuple `(fig, lscene)` where `fig` is the figure object and `lscene` is the LScene object used for plotting. These can be further manipulated or saved by the user.
+
+# Notes
+
+The keyword argument `location` can be in the either type: 
+
+- `Nothing` (default): Create a new figure and plot the Bloch sphere.
+- `GridPosition`: Plot the Bloch sphere in the specified location of the plot in the layout.
+- `LScene`: Update the existing Bloch sphere using new data and settings in `b::Bloch` without creating new `Figure` and `LScene` (efficient for drawing animation).
 """
 function QuantumToolbox.render(b::Bloch; location = nothing)
-    fig, lscene = _setup_bloch_plot!(b, location)
+    fig, lscene = _setup_bloch_plot!(location)
+    _setup_bloch_camara!(b, lscene)
     _draw_bloch_sphere!(b, lscene)
     _add_labels!(b, lscene)
 
@@ -358,13 +368,12 @@ function QuantumToolbox.render(b::Bloch; location = nothing)
 end
 
 raw"""
-    _setup_bloch_plot!(b::Bloch, location) -> (fig, lscene)
+    _setup_bloch_plot!(location) -> (fig, lscene)
 
 Initialize the figure and `3D` axis for Bloch sphere visualization.
 
 # Arguments
-- `b::Bloch`: Bloch sphere object containing view parameters
-- `location`: Figure layout position specification
+- `location`: Figure layout position specification, or directly `Makie.LScene` for update
 
 # Returns
 - `fig`: Created Makie figure
@@ -372,16 +381,33 @@ Initialize the figure and `3D` axis for Bloch sphere visualization.
 
 Sets up the `3D` coordinate system with appropriate limits and view angles.
 """
-function _setup_bloch_plot!(b::Bloch, location)
+function _setup_bloch_plot!(location)
     fig, location = _getFigAndLocation(location)
     lscene = LScene(location, show_axis = false, scenekw = (clear = true,))
+    return fig, lscene
+end
+
+function _setup_bloch_plot!(lscene::LScene)
+    # this function only removes all existing Plots in lscene
+    # it is useful for users to just update Bloch sphere without creating new figure and lscene (efficient for drawing animation)
+    fig = lscene.parent
+    empty!(lscene.scene.plots)
+    return fig, lscene
+end
+
+raw"""
+    _setup_bloch_camara!(b::Bloch, lscene)
+
+Setup the distance and viewing angle of the camara.
+"""
+function _setup_bloch_camara!(b::Bloch, lscene)
     length(b.view) == 2 || throw(ArgumentError("The length of `Bloch.view` must be 2."))
     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
     update_cam!(lscene.scene, cam, deg2rad(b.view[1]), deg2rad(b.view[2]), dist)
-    return fig, lscene
+    return nothing
 end
 
 raw"""

From 4ef4c413146a97e71c95667e84d41fd765d5f368 Mon Sep 17 00:00:00 2001
From: Yi-Te Huang <y.t.d.huang@phys.ncku.edu.tw>
Date: Fri, 1 Aug 2025 11:20:22 +0800
Subject: [PATCH 2/6] add tests

---
 test/ext-test/cpu/makie/makie_ext.jl | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/test/ext-test/cpu/makie/makie_ext.jl b/test/ext-test/cpu/makie/makie_ext.jl
index cf4e3eaf9..d19203735 100644
--- a/test/ext-test/cpu/makie/makie_ext.jl
+++ b/test/ext-test/cpu/makie/makie_ext.jl
@@ -220,4 +220,12 @@ end
         @test false
         @info "Render threw unexpected error" exception=e
     end
+
+    # if render location is given as lscene, should return the same Figure and LScene
+    b = Bloch()
+    fig1, lscene1 = render(b)
+    add_states!(b, ψ₁)
+    fig2, lscene2 = render(b, location = lscene1)
+    @test fig2 === fig1
+    @test lscene2 === lscene1
 end

From e032c097c7a70c7408da9e33386cd17b5d55b2e5 Mon Sep 17 00:00:00 2001
From: Yi-Te Huang <y.t.d.huang@phys.ncku.edu.tw>
Date: Fri, 1 Aug 2025 11:20:38 +0800
Subject: [PATCH 3/6] update changelog

---
 CHANGELOG.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3ed85a05b..46b6bb5cd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased](https://github.com/qutip/QuantumToolbox.jl/tree/main)
 
+- Improve Bloch sphere rendering for animation. ([#520])
+
 ## [v0.34.0]
 Release date: 2025-07-29
 
@@ -292,3 +294,4 @@ Release date: 2024-11-13
 [#513]: https://github.com/qutip/QuantumToolbox.jl/issues/513
 [#515]: https://github.com/qutip/QuantumToolbox.jl/issues/515
 [#517]: https://github.com/qutip/QuantumToolbox.jl/issues/517
+[#520]: https://github.com/qutip/QuantumToolbox.jl/issues/520

From 5ccb1b90fdf36e94a62cfaac692c47c16a84a0d9 Mon Sep 17 00:00:00 2001
From: Yi-Te Huang <44385685+ytdHuang@users.noreply.github.com>
Date: Fri, 1 Aug 2025 11:23:48 +0800
Subject: [PATCH 4/6] fix docstrings

---
 ext/QuantumToolboxMakieExt.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ext/QuantumToolboxMakieExt.jl b/ext/QuantumToolboxMakieExt.jl
index 0a135a500..32e0e484e 100644
--- a/ext/QuantumToolboxMakieExt.jl
+++ b/ext/QuantumToolboxMakieExt.jl
@@ -337,7 +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::Union{GridPosition,LScene,Nothing}`: The location of the plot in the layout or `Makie.LScene`
+- `location::Union{GridPosition,LScene,Nothing}`: The location of the plot in the layout, or `Makie.LScene`. Default is `nothing`.
 
 
 # Returns

From b524893f23b98fb37d34ab6a3f697e061efd489f Mon Sep 17 00:00:00 2001
From: Yi-Te Huang <44385685+ytdHuang@users.noreply.github.com>
Date: Fri, 1 Aug 2025 11:28:27 +0800
Subject: [PATCH 5/6] fix docstrings

---
 ext/QuantumToolboxMakieExt.jl | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/ext/QuantumToolboxMakieExt.jl b/ext/QuantumToolboxMakieExt.jl
index 32e0e484e..14dddad69 100644
--- a/ext/QuantumToolboxMakieExt.jl
+++ b/ext/QuantumToolboxMakieExt.jl
@@ -370,16 +370,14 @@ end
 raw"""
     _setup_bloch_plot!(location) -> (fig, lscene)
 
-Initialize the figure and `3D` axis for Bloch sphere visualization.
+Initialize the Figure and LScene for Bloch sphere visualization.
 
 # Arguments
-- `location`: Figure layout position specification, or directly `Makie.LScene` for update
+- `location`: Figure layout position specification, or directly `Makie.LScene` for updating Bloch sphere.
 
 # Returns
 - `fig`: Created Makie figure
 - `lscene`: Configured LScene object
-
-Sets up the `3D` coordinate system with appropriate limits and view angles.
 """
 function _setup_bloch_plot!(location)
     fig, location = _getFigAndLocation(location)
@@ -398,7 +396,7 @@ end
 raw"""
     _setup_bloch_camara!(b::Bloch, lscene)
 
-Setup the distance and viewing angle of the camara.
+Setup the distance and view angle of the camara.
 """
 function _setup_bloch_camara!(b::Bloch, lscene)
     length(b.view) == 2 || throw(ArgumentError("The length of `Bloch.view` must be 2."))

From 2eead23f254b4ec5d2d3d2a3a85780904f316182 Mon Sep 17 00:00:00 2001
From: Yi-Te Huang <44385685+ytdHuang@users.noreply.github.com>
Date: Fri, 1 Aug 2025 13:29:13 +0800
Subject: [PATCH 6/6] minor changes in docs

---
 docs/src/users_guide/plotting_the_bloch_sphere.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/docs/src/users_guide/plotting_the_bloch_sphere.md b/docs/src/users_guide/plotting_the_bloch_sphere.md
index 50a6ca5d2..a306d2977 100644
--- a/docs/src/users_guide/plotting_the_bloch_sphere.md
+++ b/docs/src/users_guide/plotting_the_bloch_sphere.md
@@ -243,19 +243,22 @@ c_op_list = (
 ψ0 = basis(2, 0)
 tlist = LinRange(0, 4, 250)
 sol = mesolve(H, ψ0, tlist, c_op_list, e_ops = (sx, sy, sz), progress_bar = Val(false))
-x = real(sol.expect[1,:])
-y = real(sol.expect[2,:])
-z = real(sol.expect[3,:])
 ```
 
 To animate a set of vectors or data points, we use the `record` function provided by [`Makie.jl`](https://docs.makie.org/stable/):
 
 ```@example Bloch_sphere_rendering
+# expectation values
+x = real(sol.expect[1,:])
+y = real(sol.expect[2,:])
+z = real(sol.expect[3,:])
+
+# create Bloch sphere
 b = Bloch()
 b.view = [50,30]
-
 fig, lscene = render(b)
 
+# save animation
 record(fig, "qubit_decay.mp4", eachindex(tlist), framerate = 20) do idx
     clear!(b)
     add_vectors!(b, [sin(θ), 0, cos(θ)])