Fix Bloch docstrings and improve visualization of the sphere (#487)

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()
 ```
@@ -163,19 +166,25 @@ fig
 
 ## [Configuring the Bloch sphere](@id doc:Configuring-the-Bloch-sphere)
 
-At the end of the last section we saw that the colors and marker shapes of the data plotted on the Bloch sphere are automatically varied according to the number of points and vectors added. But what if you want a different choice of color, or you want your sphere to be purple with different axes labels? Well then you are in luck as the Bloch class has many attributes which one can control. Assuming `b = Bloch()`:
+At the end of the last section we saw that the colors and marker shapes of the data plotted on the Bloch sphere are automatically varied according to the number of points and vectors added. But what if you want a different choice of color, or you want your sphere to be purple with different axes labels? Well then you are in luck as the [`Bloch`](@ref) structure has many fields which one can control. Assuming `b = Bloch()`:
+
+### Data storage
 
 | **Field** | **Description** | **Default setting** |
 |:----------|:----------------|:--------------------|
 | `b.points` | Points to plot on the Bloch sphere (3D coordinates) | `Vector{Matrix{Float64}}()` (empty) |
 | `b.vectors` | Vectors to plot on the Bloch sphere | `Vector{Vector{Float64}}()` (empty) |
-| `b.lines` | Lines to draw on the sphere (points, style, properties) | `Vector{Tuple{Vector{Vector{Float64}},String}}()` (empty) |
+| `b.lines` | Lines to draw on the sphere with each line given as `([start_pt, end_pt], line_format)` | `Vector{Tuple{Vector{Vector{Float64}},String}}()` (empty) |
 | `b.arcs` | Arcs to draw on the sphere | `Vector{Vector{Vector{Float64}}}()` (empty) |
+
+### Properties
+
+| **Field** | **Description** | **Default setting** |
+|:----------|:----------------|:--------------------|
 | `b.font_color` | Color of axis labels and text | `"black"` |
-| `b.font_size` | Font size for labels | `15` |
-| `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` |
+| `b.font_size` | Font size for labels | `20` |
+| `b.frame_alpha` | Transparency of the wire frame | `0.1` |
+| `b.frame_color` | Color of the wire frame | `"gray"` |
 | `b.point_default_color` | Default color cycle for points | `["blue", "red", "green", "#CC6600"]` |
 | `b.point_color` | List of colors for Bloch point markers to cycle through | `Union{Nothing,String}[]` |
 | `b.point_marker` | List of point marker shapes to cycle through | `[:circle, :rect, :diamond, :utriangle]` |
@@ -186,14 +195,14 @@ At the end of the last section we saw that the colors and marker shapes of the d
 | `b.sphere_alpha` | Transparency of sphere surface | `"#FFDDDD"` |
 | `b.vector_color` | Colors for vectors | `["green", "#CC6600", "blue", "red"]` |
 | `b.vector_width` | Width of vectors | `0.025` |
-| `b.vector_arrowsize` | Arrow size parameters as (head length, head width, stem width) | `[0.07, 0.08, 0.08]` |
+| `b.vector_arrowsize` | Scales the size of the arrow head. The first two elements scale the radius (in `x/y` direction) and the last one is the length of the cone. | `[0.07, 0.08, 0.08]` |
 | `b.view` | Azimuthal and elevation viewing angles in degrees | `[30, 30]` |
 | `b.xlabel` | Labels for x-axis | `[L"x", ""]` (``+x`` and ``-x``) |
-| `b.xlpos` | Positions of x-axis labels | `[1.0, -1.0]` |
+| `b.xlpos` | Positions of x-axis labels | `[1.2, -1.2]` |
 | `b.ylabel` | Labels for y-axis | `[L"y", ""]` (``+y`` and ``-y``) |
-| `b.ylpos` | Positions of y-axis labels | `[1.0, -1.0]` |
+| `b.ylpos` | Positions of y-axis labels | `[1.2, -1.2]` |
 | `b.zlabel` | Labels for z-axis | `[L"\|0\rangle", L"\|1\rangle]"` (``+z`` and ``-z``) |
-| `b.zlpos` | Positions of z-axis labels | `[1.0, -1.0]` |
+| `b.zlpos` | Positions of z-axis labels | `[1.2, -1.2]` |
 
 These properties can also be accessed via the `print` command: