update docs

QuantumBFS · Feb 20, 2024 · 44823ca · 44823ca
1 parent a09b19c
commit 44823ca
Show file tree

Hide file tree

Showing 14 changed files with 136 additions and 21 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -39,6 +39,7 @@ jobs:
           - YaoArrayRegister
           - YaoBlocks
           - YaoSym
+          - YaoPlots
     steps:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@v1

diff --git a/docs/make.jl b/docs/make.jl
@@ -2,7 +2,7 @@ using Documenter
 using DocThemeIndigo
 using Literate
 using Yao
-using Yao: YaoBlocks, YaoArrayRegister, YaoSym, BitBasis, YaoAPI
+using Yao: YaoBlocks, YaoArrayRegister, YaoSym, BitBasis, YaoAPI, YaoPlots
 using YaoBlocks: AD
 using YaoBlocks: Optimise
 
@@ -63,6 +63,7 @@ const PAGES = [
         "man/registers.md",
         "man/blocks.md",
         "man/symbolic.md",
+        "man/plot.md",
         "man/automatic_differentiation.md",
         "man/simplification.md",
         "man/bitbasis.md",

diff --git a/docs/src/examples/6.quantum-circuit-born-machine/main.jl b/docs/src/examples/6.quantum-circuit-born-machine/main.jl
@@ -27,7 +27,7 @@ pg = gaussian_pdf(1:1<<6, 1<<5-0.5, 1<<4);
 
 # We can plot the distribution, it looks like
 
-plot(pg)
+Plots.plot(pg)
 
 # ## Create the Circuit
 
@@ -225,12 +225,12 @@ trained_pg = probs(zero_state(nqubits(qcbm)) |> qcbm)
 
 title!("training history")
 xlabel!("steps"); ylabel!("loss")
-plot(history)
+Plots.plot(history)
 
 # And let's check what we got
 
-fig2 = plot(1:1<<6, trained_pg; label="trained")
-plot!(fig2, 1:1<<6, pg; label="target")
+fig2 = Plots.plot(1:1<<6, trained_pg; label="trained")
+Plots.plot!(fig2, 1:1<<6, pg; label="target")
 title!("distribution")
 xlabel!("x"); ylabel!("p")
 

diff --git a/docs/src/examples/8.riemannian-gradient-flow/main.jl b/docs/src/examples/8.riemannian-gradient-flow/main.jl
@@ -42,8 +42,8 @@ for i in 1:100
     push!(history, real.(expect(h, zero_state(n)=>circuit)))
 end
 
-plot(history, legend=false)
-plot!(1:100, [w[1] for i=1:100])
+Plots.plot(history, legend=false)
+Plots.plot!(1:100, [w[1] for i=1:100])
 xlabel!("steps")
 ylabel!("energy")
 
@@ -134,8 +134,8 @@ for i=1:100
     push!(history, cost)
 end
 
-plot(history, legend=false)
-plot!(1:100, [w[1] for i=1:100])
+Plots.plot(history, legend=false)
+Plots.plot!(1:100, [w[1] for i=1:100])
 xlabel!("steps")
 ylabel!("energy")
 

diff --git a/docs/src/man/plot.md b/docs/src/man/plot.md
@@ -0,0 +1,34 @@
+```@meta
+CurrentModule = YaoPlots
+DocTestSetup = quote
+    using Yao
+    using Yao: YaoBlocks, YaoArrayRegister, YaoSym
+    using YaoBlocks
+    using YaoArrayRegister
+    using YaoPlots
+end
+```
+
+# Quantum Circuit Visualization
+
+Quantum circuit visualization support for Yao.
+
+## Circuit Visualization
+```@docs
+vizcircuit
+plot
+```
+
+## Bloch Sphere Visualization
+
+```@docs
+CircuitStyles
+bloch_sphere
+BlochStyles
+```
+
+## Themes
+```@docs
+darktheme!
+lighttheme!
+```
diff --git a/lib/YaoPlots/src/YaoPlots.jl b/lib/YaoPlots/src/YaoPlots.jl
@@ -1,17 +1,19 @@
 module YaoPlots
 
 using YaoBlocks
+using YaoBlocks.DocStringExtensions
+using YaoArrayRegister
 import Luxor
 import Thebes
 using Luxor: @layer, Point
 using Thebes: Point3D, project
-using YaoBlocks.DocStringExtensions
 using LinearAlgebra: tr
 
-export CircuitStyles, CircuitGrid, circuit_canvas, vizcircuit, darktheme!, lighttheme!
+export CircuitStyles, vizcircuit, darktheme!, lighttheme!
 export bloch_sphere, BlochStyles
 export plot
 
+"""An alias of `vizcircuit`"""
 plot(;kwargs...) = x->plot(x;kwargs...)
 plot(blk::AbstractBlock; kwargs...) = vizcircuit(blk; kwargs...)
 

diff --git a/lib/YaoPlots/src/bloch.jl b/lib/YaoPlots/src/bloch.jl
@@ -1,3 +1,37 @@
+"""
+    BlochStyles
+
+The module to define the default styles for bloch sphere drawing.
+To change the default styles, you can modify the values in this module, e.g.
+```julia
+using YaoPlots
+YaoPlots.BlochStyles.lw[] = 2.0
+```
+
+### Style variables
+#### Generic
+- `lw`: the line width of the drawing
+- `textsize`: the size of the text
+- `fontfamily`: the font family of the text
+- `background_color`: the background color of the drawing
+- `color`: the color of the drawing
+
+#### Sphere
+- `ball_size`: the size of the ball
+- `dot_size`: the size of the dot
+- `eye_point`: the eye point of the drawing
+
+#### Axis
+- `axes_lw`: the line width of the axes
+- `axes_colors`: the colors of the axes
+- `axes_texts`: the texts of the axes, default to `["x", "y", "z"]`
+
+#### State display
+- `show_projection_lines`: whether to show the projection lines
+- `show_angle_texts`: whether to show the angle texts
+- `show_line`: whether to show the line
+- `show01`: whether to show the 0 and 1 states
+"""
 module BlochStyles
     using Luxor
     # generic config
@@ -61,7 +95,7 @@ Note: The default values can be specified in submodule `BlochStyles`.
 ### Examples
 
 ```jldoctest
-julia> using YaoPlots, YaoBlocks, Luxor
+julia> using YaoPlots, YaoArrayRegister
 
 julia> bloch_sphere("|ψ⟩"=>rand_state(1), "ρ"=>density_matrix(rand_state(2), 1));
 ```

diff --git a/lib/YaoPlots/src/vizcircuit.jl b/lib/YaoPlots/src/vizcircuit.jl
@@ -1,6 +1,34 @@
+"""
+    CircuitStyles
+
+A module to define the styles of the circuit visualization.
+To change the styles, please modify the variables in this module, e.g.
+```julia
+julia> using YaoPlots
+
+julia> YaoPlots.CircuitStyles.unit[] = 40
+40
+```
+
+### Style variables
+#### Sizes
+* `unit` is the number of pixels in a unit.
+* `r` is the size of nodes.
+* `lw` is the line width.
+
+#### Texts
+* `textsize` is the text size.
+* `paramtextsize` is the text size for longer texts.
+* `fontfamily` is the font family.
+
+#### Colors
+* `linecolor` is the line color.
+* `gate_bgcolor` is the gate background color.
+* `textcolor` is the text color.
+"""
 module CircuitStyles
     using Luxor
-    const unit = Ref(60)    # number of points in a unit
+    const unit = Ref(60)    # number of pixels in a unit
     const barrier_for_chain = Ref(false)
     const r = Ref(0.2)
     const lw = Ref(1.0)
@@ -492,13 +520,23 @@ end
 
 vizcircuit(; kwargs...) = c->vizcircuit(c; kwargs...)
 
+"""
+    darktheme!()
+
+Change the default theme to dark.
+"""
 function darktheme!()
     const CircuitStyles.linecolor[] = "#FFFFFF"
     const CircuitStyles.textcolor[] = "#FFFFFF"
     const BlochStyles.color[] = "#FFFFFF"
     BlochStyles.axes_colors .= ["#FFFFFF", "#FFFFFF", "#FFFFFF"]
 end
 
+"""
+    lighttheme!()
+
+Change the default theme to light.
+"""
 function lighttheme!()
     const CircuitStyles.linecolor[] = "#000000"
     const CircuitStyles.textcolor[] = "#000000"

diff --git a/lib/YaoPlots/test/bloch.jl b/lib/YaoPlots/test/bloch.jl
@@ -2,6 +2,7 @@ using YaoPlots, Test
 using LinearAlgebra: normalize!, eigen
 using Luxor: Drawing
 using YaoBlocks
+using YaoArrayRegister
 
 @testset "spherical coo" begin
     for i=1:10

diff --git a/lib/YaoPlots/test/helperblock.jl b/lib/YaoPlots/test/helperblock.jl
@@ -1,4 +1,5 @@
 using YaoPlots, YaoBlocks, Luxor
+using YaoArrayRegister
 using Test
 
 @testset "LabelBlock" begin

diff --git a/lib/YaoPlots/test/vizcircuit.jl b/lib/YaoPlots/test/vizcircuit.jl
@@ -2,6 +2,7 @@ using YaoPlots
 using Test
 using YaoBlocks
 using YaoPlots: addblock!
+using YaoArrayRegister
 using Luxor
 
 @testset "gate styles" begin
@@ -76,10 +77,6 @@ end
     @test plot(chain(3, put(1=>X), repeat(3, H), put(2=>Y), repeat(3, Rx(π/2)))) isa Drawing
 end
 
-@testset "regression" begin
-	@test vizcircuit(put(10, (8,2,3)=>EasyBuild.heisenberg(3)), starting_texts=string.(1:10), ending_texts=string.(1:10), show_ending_bar=true) isa Drawing
-end
-
 @testset "readme" begin
     circuit = chain(
         4,    

diff --git a/lib/YaoSym/src/register.jl b/lib/YaoSym/src/register.jl
@@ -35,14 +35,14 @@ Create a ket register. See also [`@bra_str`](@ref).
 
 a symbolic quantum state can be created simply by
 
-```jldoctest; setup=:(using Yao, SymEngine)
+```jldoctest; setup=:(using Yao)
 julia> ket"110" + 2ket"111"
 |110⟩ + 2.0|111⟩
 ```
 
 qubits can be partially actived by [`focus!`](@ref)
 
-```jldoctest; setup=:(using Yao, SymEngine)
+```jldoctest; setup=:(using Yao)
 julia> ket"100" + ket"111" |> focus!(1:2)
 |100⟩ + |111⟩
 ```
@@ -62,7 +62,7 @@ Create a bra register. See also [`@ket_str`](@ref).
 Similar to `@ket_str` literal, a symbolic quantum state can be created
 by
 
-```jldoctest; setup=:(using Yao, SymEngine)
+```jldoctest; setup=:(using Yao)
 julia> bra"111" + 2bra"101"
 2.0⟨101| + ⟨111|
 

diff --git a/test/easybuild/block_extension/shortcuts.jl b/test/easybuild/block_extension/shortcuts.jl
@@ -1,6 +1,7 @@
 using Test, Yao.EasyBuild, YaoBlocks
 using YaoBlocks.Optimise: replace_block, to_basictypes, simplify
 using YaoBlocks: parse_ex
+using YaoPlots: vizcircuit, Luxor
 
 @testset "gates" begin
     @test isunitary(FSimGate(0.5, 0.6))
@@ -21,3 +22,7 @@ using YaoBlocks: parse_ex
 
     @test Matrix(c) ≈ Matrix(simplify(c_, rules=[to_basictypes]))
 end
+
+@testset "regression" begin
+	@test vizcircuit(put(10, (8,2,3)=>heisenberg(3)), starting_texts=string.(1:10), ending_texts=string.(1:10), show_ending_bar=true) isa Luxor.Drawing
+end
diff --git a/test/runtests.jl b/test/runtests.jl
@@ -12,10 +12,11 @@ using Random
     include("easybuild/easybuild.jl")
 end
 
-DocMeta.setdocmeta!(Yao, :DocTestSetup, :(using Yao, YaoAPI, YaoArrayRegister, YaoBlocks, YaoSym, BitBasis); recursive=true)
+DocMeta.setdocmeta!(Yao, :DocTestSetup, :(using Yao, YaoAPI, YaoArrayRegister, YaoBlocks, YaoPlots, YaoSym, BitBasis); recursive=true)
 
 Documenter.doctest(YaoAPI; manual=false)
 Documenter.doctest(YaoArrayRegister; manual=false)
 Documenter.doctest(YaoBlocks; manual=false)
 Documenter.doctest(YaoSym; manual=false)
+Documenter.doctest(YaoPlots; manual=false)
 Documenter.doctest(Yao; manual=false)