Include YaoPlots as a component package (#493)

* initial

* update docs

* fix documentation

* fix tests

.github/workflows/CI.yml

@@ -39,6 +39,7 @@ jobs:
           - YaoArrayRegister
           - YaoBlocks
           - YaoSym
+          - YaoPlots
     steps:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@v1

.gitignore

@@ -31,3 +31,5 @@ docs/src/assets/*.pdf
 *.synctex.gz
 *.fls
 *.log
+lib/YaoPlots/examples/*.png
+lib/YaoPlots/examples/*.svg

Project.toml

@@ -10,6 +10,7 @@ Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 YaoAPI = "0843a435-28de-4971-9e8b-a9641b2983a8"
 YaoArrayRegister = "e600142f-9330-5003-8abb-0ebd767abc51"
 YaoBlocks = "418bc28f-b43b-5e0b-a6e7-61bbc1a2c1df"
+YaoPlots = "32cfe2d9-419e-45f2-8191-2267705d8dbc"
 YaoSym = "3b27209a-d3d6-11e9-3c0f-41eb92b2cb9d"
 
 [compat]

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",
@@ -74,7 +75,7 @@ const PAGES = [
 indigo = DocThemeIndigo.install(Yao)
 
 makedocs(
-    modules = [Yao, YaoAPI, YaoArrayRegister, YaoBlocks, BitBasis, YaoSym, AD, Optimise],
+    modules = [Yao, YaoAPI, YaoArrayRegister, YaoBlocks, BitBasis, YaoSym, YaoPlots, AD, Optimise],
     format = Documenter.HTML(
         prettyurls = ("deploy" in ARGS),
         canonical = ("deploy" in ARGS) ? "https://docs.yaoquantum.org/" : nothing,
@@ -88,6 +89,7 @@ makedocs(
     sitename = "Documentation | Yao",
     linkcheck = !("skiplinks" in ARGS),
     pages = PAGES,
+    warnonly = [:missing_docs, :linkcheck, :cross_references],
 )
 
 

docs/src/examples/1.prepare-ghz-state/index.md

@@ -6,7 +6,7 @@ EditURL = "<unknown>/docs/src/quick-start/1.prepare-ghz-state/main.jl"
 [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](<unknown>/generated//home/roger/code/julia/Yao/docs/src/quick-start/1.prepare-ghz-state/main.ipynb)
 [![](https://img.shields.io/badge/download-project-orange)](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/QuantumBFS/tutorials/tree/gh-pages/dev/generated//home/roger/code/julia/Yao/docs/src/quick-start/1.prepare-ghz-state)
 
-# [Prepare Greenberger–Horne–Zeilinger state with Quantum Circuit](@id example-ghz)
+# [Prepare Greenberger–Horne–Zeilinger state with Quantum Circuit](@id tutorial-ghz)
 
 First, you have to use this package in Julia.
 

docs/src/examples/2.qft-phase-estimation/main.jl

@@ -32,7 +32,7 @@ A(i, j) = control(i, j=>shift(2π/(1<<(i-j+1))))
 
 R4 = A(4, 1)
 
-# If you have read about [preparing GHZ state](@ref example-ghz),
+# If you have read about [preparing GHZ state](@ref tutorial-ghz),
 # you probably know that in Yao, we could just leave the number of qubits, and it
 # will be evaluated when possible.
 

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")
 

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")
 

docs/src/index.md

@@ -26,7 +26,7 @@ The tutorials are written with [Literate](https://github.com/fredrikekre/Literat
 
 ## Pluto Notebooks
 
-There is also a set of Pluto notebooks available in [the notebooks folder](https://github.com/QuantumBFS/Yao.jl/notebooks)
+There is also a set of Pluto notebooks available in [the notebooks folder](notebooks)
 
 ## Manual
 

docs/src/man/bitbasis.md

@@ -1,4 +1,5 @@
 ```@meta
+CurrentModule = BitBasis
 DocTestSetup = quote
     using Yao
     using Yao: YaoBlocks, YaoArrayRegister
@@ -16,4 +17,4 @@ For more details please ref to [BitBasis.jl](https://quantumbfs.github.io/BitBas
 ```@autodocs
 Modules = [BitBasis]
 Order = [:macro, :function, :type, :module]
-```
+```

docs/src/man/blocks.md

@@ -1,4 +1,5 @@
 ```@meta
+CurrentModule = YaoBlocks
 DocTestSetup = quote
     using Yao
     using Yao: YaoBlocks, YaoArrayRegister
@@ -10,13 +11,19 @@ end
 # Blocks
 
 **Blocks** are the basic building blocks of a quantum circuit in Yao.
-It simply means a quantum operator, thus, all the blocks have matrices in principal and one can get its matrix by [`mat`](@ref). The basic blocks required to build an arbitrary quantum circuit is defined in the component package [`YaoBlocks`](@ref).
+It simply means a quantum operator, thus, all the blocks have matrices in principal and one can get its matrix by [`mat`](@ref). The basic blocks required to build an arbitrary quantum circuit is defined in the component package `YaoBlocks`.
 
 Block Tree serves as an intermediate representation for Yao to analysis, optimize the circuit, then it will be lowered to instructions like for simulations, blocks will be lowered to [`instruct!`](@ref) calls.
 
 The structure of blocks is the same with a small type system, it consists of two basic kinds of blocks: [`CompositeBlock`](@ref) (like composite types), and [`PrimitiveBlock`](@ref) (like primitive types). By combining these two kinds of blocks together, we'll be able to
 construct a quantum circuit and represent it in a tree data structure.
 
+```@docs
+AbstractBlock
+PrimitiveBlock
+CompositeBlock
+```
+
 ## Primitive Blocks
 
 Primitive blocks are subtypes of [`PrimitiveBlock`](@ref), they are the leaf nodes in a block tree, thus primitive types do not have subtypes.
@@ -28,6 +35,10 @@ Modules = [YaoBlocks]
 Filter = t ->(t isa Type && t <: YaoBlocks.PrimitiveBlock)
 ```
 
+```@docs
+@const_gate
+```
+
 ## Composite Blocks
 
 Composite blocks are subtypes of [`CompositeBlock`](@ref), they are the composition of blocks.
@@ -39,6 +50,24 @@ Modules = [YaoBlocks]
 Filter = t -> t isa Type && t <: YaoBlocks.CompositeBlock
 ```
 
+## Operations on Blocks
+```@docs
+unsafe_apply!
+apply!
+apply
+
+niparams
+getiparams
+render_params
+nparameters
+
+occupied_locs
+print_block
+
+apply_back!
+mat_back!
+```
+
 ## Error and Exceptions
 
 ```@autodocs

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!
+```

docs/src/man/registers.md

@@ -1,7 +1,9 @@
 ```@meta
+CurrentModule = YaoArrayRegister
 DocTestSetup = quote
     using Yao
-    using Yao: YaoBlocks, YaoArrayRegister
+    using BitBasis
+    using YaoAPI
     using YaoBlocks
     using YaoArrayRegister
 end
@@ -44,18 +46,17 @@ nqudits
 nqubits
 nactive
 nremain
-nbatch,
-nlevel,
+nbatch
+nlevel
 focus!
 focus
 relax!
-zero_state
 exchange_sysenv
 ```
 
 ## Storage
 
-Both [`ArayReg`](@reef) and [`BatchedArrayReg`](@ref) use matrices as the storage. For example, for a quantum register with ``a`` active qubits, ``r`` remaining qubits and batch size ``b``, the storage is as follows
+Both [`ArrayReg`](@ref) and [`BatchedArrayReg`](@ref) use matrices as the storage. For example, for a quantum register with ``a`` active qubits, ``r`` remaining qubits and batch size ``b``, the storage is as follows
 
 ![](../assets/images/regstorage.svg)
 
@@ -98,9 +99,9 @@ AdjointArrayReg
 
 We also have some faster inplace versions of arithematic operations
 ```@docs
-regadd!,
-regsub!,
-regscale!,
+regadd!
+regsub!
+regscale!
 ```
 
 We also define the following functions for state normalization, and distance measurement.
@@ -114,8 +115,8 @@ tracedist
 ## Resource management and addressing
 
 ```@docs
-add_qudits!
-add_qubits!
+insert_qudits!
+insert_qubits!
 append_qudits!
 append_qubits!
 reorder!
@@ -146,7 +147,7 @@ select!
 select
 collapseto!
 probs
-most_probable,
+most_probable
 ```
 
 ## Density matrices
@@ -158,6 +159,6 @@ rand_density_matrix
 completely_mixed_state
 partial_tr
 purify
-von_neumann_entropy,
-mutual_information,
+von_neumann_entropy
+mutual_information
 ```

docs/src/man/symbolic.md

@@ -16,6 +16,5 @@ Symbolic Computation support for Yao
 ```@docs
 @ket_str
 @bra_str
-@vars
 szero_state
 ```

docs/src/quick-start.md

@@ -24,7 +24,7 @@ the internal quantum state can be accessed via [`statevec`](@ref) method
 statevec(ghz_state(2))
 ```
 
-for more functionalities about registers please refer to the manual of [`registers`](@ref).
+for more functionalities about registers please refer to the manual of [Registers](@ref registers).
 
 ## Create quantum circuit with Yao blocks
 
@@ -80,15 +80,12 @@ Yao supports symbolic calculation of quantum circuit via `SymEngine`. We can sho
 
 ## Plot quantum circuits
 
-The [YaoPlots]() in Yao's ecosystem provides plotting for quantum circuits and ZX diagrams.
+The component package `YaoPlots` provides plotting for quantum circuits and ZX diagrams.
 
 ```@example quick-start
-using Yao.EasyBuild, YaoPlots
+using Yao.EasyBuild, Yao.YaoPlots
 using Compose
 
 # show a qft circuit
-Compose.SVG(plot(qft_circuit(5)))
-```
-
-## Convert quantum circuits to tensor network
-## Simplify quantum circuit with ZX calculus
+vizcircuit(qft_circuit(5))
+```

lib/YaoAPI/src/blocks.jl

@@ -3,7 +3,7 @@ export AbstractBlock, PrimitiveBlock, CompositeBlock, AbstractContainer, TagBloc
 const COMMON_OPTIONAL_METHODS = """
 - [`nlevel`](@ref).
 - [`getiparams`](@ref).
-- [`setiparams`](@ref).
+- [`setiparams!`](@ref).
 - [`parameters`](@ref).
 - [`nparameters`](@ref).
 - [`iparams_eltype`](@ref).
@@ -63,7 +63,7 @@ block can be decomposed into several primitive blocks.
 
 - [`nlevel`](@ref).
 - [`getiparams`](@ref).
-- [`setiparams`](@ref).
+- [`setiparams!`](@ref).
 - [`parameters`](@ref).
 - [`nparameters`](@ref).
 - [`iparams_eltype`](@ref).
@@ -94,7 +94,7 @@ as well.
 
 - [`nlevel`](@ref).
 - [`getiparams`](@ref).
-- [`setiparams`](@ref).
+- [`setiparams!`](@ref).
 - [`parameters`](@ref).
 - [`nparameters`](@ref).
 - [`iparams_eltype`](@ref).

lib/YaoAPI/src/registers.jl

@@ -609,8 +609,8 @@ julia> reg |> probs
 
 Return the fidelity between two states.
 Calcuate the fidelity between `r1` and `r2`, if `r1` or `r2` is not pure state
-(`nactive(r) != nqudits(r)`), the fidelity is calcuated by purification. See also
-[`pure_state_fidelity`](@ref), [`purification_fidelity`](@ref).
+(`nactive(r) != nqudits(r)`), the fidelity is calcuated by purification. See also:
+http://iopscience.iop.org/article/10.1088/1367-2630/aa6a4b/meta
 
 Obtain the gradient with respect to registers and circuit parameters.
 For pair input `ψ=>circuit`, the returned gradient is a pair of `gψ=>gparams`,

lib/YaoArrayRegister/Project.toml

@@ -18,7 +18,7 @@ TupleTools = "9d95972d-f1c8-5527-a6e0-b4b365fa01f6"
 YaoAPI = "0843a435-28de-4971-9e8b-a9641b2983a8"
 
 [compat]
-Adapt = "3"
+Adapt = "3, 4"
 BitBasis = "0.8, 0.9"
 DocStringExtensions = "0.8, 0.9"
 LegibleLambdas = "0.3"