Add more test (#28)

* add doc test

* add test for pauli_string; add doc test to ci

* update ignore

* rm build cache

* add more test

* update travis

* update travis

* add more doctests

* fix dispatch for phase gate, add test

* update travis

* Update .travis.yml

Co-Authored-By: Roger-luo <[email protected]>

* add some docs

* fix qcbm dispatch

* fix counting

* rm print

* add tests for qcbm

* update docs Project.toml

* rm name

* add a comment

Author: Roger-luo

.gitignore

@@ -3,3 +3,6 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+
+docs/build/
+docs/site/

.travis.yml

@@ -13,6 +13,14 @@ matrix:
   fast_finish: true
 notifications:
   email: false
+jobs:
+  include:
+    - stage: "DocTest"
+      julia: 1.1 # we only do doc test on latest stable release
+      os: linux
+      script:
+        - julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+        - julia --project=docs/ --code-coverage=user docs/make.jl
 after_success:
   - julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; Codecov.submit(process_folder())'
   - julia -e 'using Pkg; Pkg.add("Coverage"); using Coverage; Coveralls.submit(process_folder())'

docs/Project.toml

@@ -0,0 +1,7 @@
+[deps]
+BitBasis = "50ba71b6-fa0f-514d-ae9a-0916efc90dcf"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+YaoArrayRegister = "e600142f-9330-5003-8abb-0ebd767abc51"
+YaoBase = "a8f54c17-34bc-5a9d-b050-f522fe3f755f"
+YaoBlocks = "418bc28f-b43b-5e0b-a6e7-61bbc1a2c1df"
+Yao = "5872b779-8223-5990-8dd0-5abbb0748c8c"

docs/make.jl

@@ -0,0 +1,10 @@
+using Documenter
+using YaoArrayRegister, YaoBase, YaoBlocks
+
+makedocs(
+    modules = [YaoBlocks],
+    doctest = true,
+    clean = false,
+    sitename = "YaoBlocks.jl",
+    pages = ["index.md"]
+)

docs/src/index.md

@@ -0,0 +1,9 @@
+```@meta
+DocTestSetup = quote
+    using Yao, YaoBase, YaoBlocks, YaoArrayRegister
+end
+```
+
+```@autodocs
+Modules = [YaoBlocks]
+```

src/blocktools.jl

@@ -7,6 +7,8 @@ function parse_block(n::Int, x::AbstractBlock{N}) where N
     return x
 end
 
+parse_block(n::Int, x::Pair{Int, <:AbstractBlock{N}}) where N = x
+
 """
     prewalk(f, src::AbstractBlock)
 

src/composite/concentrator.jl

@@ -25,6 +25,46 @@ end
 Create a [`Concentrator`](@ref) block with total number of current active qubits `n`,
 which concentrates given wire location together to `length(locs)` active qubits,
 and relax the concentration afterwards.
+
+# Example
+
+Concentrator is equivalent to [`put`](@ref) a block on given position mathematically, but more efficient
+and convenient for large blocks.
+
+```jldoctest
+julia> r = rand_state(3)
+ArrayReg{1, Complex{Float64}, Array...}
+    active qubits: 3/3
+
+julia> apply!(copy(r), concentrate(X, 1)) ≈ apply!(copy(r), put(1=>X))
+true
+```
+
+It works for in-contigious locations as well
+
+```jldoctest
+julia> r = rand_state(4)
+ArrayReg{1, Complex{Float64}, Array...}
+    active qubits: 4/4
+
+julia> cc = concentrate(4, kron(X, Y), (1, 3))
+nqubits: 4, datatype: Complex{Float64}
+Concentrator: (1, 3)
+└─ kron
+   ├─ 1=>X gate
+   └─ 2=>Y gate
+
+julia> pp = chain(4, put(1=>X), put(3=>Y))
+nqubits: 4, datatype: Complex{Float64}
+chain
+├─ put on (1)
+│  └─ X gate
+└─ put on (3)
+   └─ Y gate
+
+julia> apply!(copy(r), cc) ≈ apply!(copy(r), pp)
+true
+```
 """
 function concentrate(n::Int, block::AbstractBlock, locs)
     return Concentrator{n}(block, Tuple(locs))

src/composite/pauli_strings.jl

@@ -10,8 +10,41 @@ end
 
 # NOTE: PauliString has a fixed size `N`, thus by default, it should use
 #      SizedVector, or this block could be actually not correct.
+
+"""
+    PauliString(xs::PauliGate...)
+
+Create a `PauliString` from some Pauli gates.
+
+# Example
+
+```jldoctest
+julia> PauliString(X, Y, Z)
+nqubits: 3, datatype: Complex{Float64}
+PauliString
+├─ X gate
+├─ Y gate
+└─ Z gate
+```
+"""
 PauliString(xs::PauliGate{T}...) where T = PauliString(SizedVector{length(xs), PauliGate{T}}(xs))
 
+"""
+    PauliString(list::Vector)
+
+Create a `PauliString` from a list of Pauli gates.
+
+# Example
+
+```jldoctest
+julia> PauliString([X, Y, Z])
+nqubits: 3, datatype: Complex{Float64}
+PauliString
+├─ X gate
+├─ Y gate
+└─ Z gate
+```
+"""
 function PauliString(xs::Vector)
     T = datatype(first(xs))
     for each in xs
@@ -38,7 +71,7 @@ YaoBase.isunitary(::PauliString) = true
 
 Base.copy(ps::PauliString) = PauliString(copy(ps.blocks))
 Base.getindex(ps::PauliString, x) = getindex(ps.blocks, x)
-Base.lastindex(ps::PauliString, x) = lastindex(ps.blocks, x)
+Base.lastindex(ps::PauliString) = lastindex(ps.blocks)
 Base.iterate(ps::PauliString) = iterate(ps.blocks)
 Base.iterate(ps::PauliString, st) = iterate(ps.blocks, st)
 Base.length(ps::PauliString) = length(ps.blocks)

src/composite/put_block.jl

@@ -21,6 +21,32 @@ end
 
 Create a [`PutBlock`](@ref) with total number of active qubits, and a pair of
 location and block to put on.
+
+# Example
+
+```jldoctest
+julia> put(4, 1=>X)
+nqubits: 4, datatype: Complex{Float64}
+put on (1)
+└─ X gate
+```
+
+If you want to put a multi-qubit gate on specific locations, you need to write down all possible locations.
+
+```jldoctest
+julia> put(4, (1, 3)=>kron(X, Y))
+nqubits: 4, datatype: Complex{Float64}
+put on (1, 3)
+└─ kron
+   ├─ 1=>X gate
+   └─ 2=>Y gate
+```
+
+The outter locations creates a scope which make it seems to be a contiguous two qubits for the block inside `PutBlock`.
+
+!!! tips
+    It is better to use [`concentrate`](@ref) instead of `put` for large blocks, since put will use the matrix of its contents
+    directly instead of making use of what's in it. `put` is more efficient for small blocks.
 """
 put(total::Int, pa::Pair{NTuple{M, Int}, <:AbstractBlock}) where M =
     PutBlock{total}(pa.second, pa.first)
@@ -31,6 +57,13 @@ put(total::Int, pa::Pair{<:Any, <:AbstractBlock}) = PutBlock{total}(pa.second, T
     put(pair) -> f(n)
 
 Lazy curried version of [`put`](@ref).
+
+# Example
+
+```jldoctest
+julia> put(1=>X)
+(n -> put(n, 1 => X gate))
+```
 """
 put(pa::Pair) = @λ(n -> put(n, pa))
 

src/composite/repeated.jl

@@ -25,6 +25,47 @@ end
 
 Create a [`RepeatedBlock`](@ref) with total number of qubits `n` and the block
 to repeat on given location or on all the locations.
+
+# Example
+
+This will create a repeat block which puts 4 X gates on each location.
+
+```jldoctest
+julia> repeat(4, X)
+nqubits: 4, datatype: Complex{Float64}
+repeat on (1, 2, 3, 4)
+└─ X gate
+```
+
+You can also specify the location
+
+```jldoctest
+julia> repeat(4, X, (1, 2))
+nqubits: 4, datatype: Complex{Float64}
+repeat on (1, 2)
+└─ X gate
+```
+
+But repeat won't copy the gate, thus, if it is a gate with parameter, e.g a `phase(0.1)`, the parameter
+will change simultaneously.
+
+```jldoctest
+julia> g = repeat(4, phase(0.1))
+nqubits: 4, datatype: Complex{Float64}
+repeat on (1, 2, 3, 4)
+└─ phase(0.1)
+
+julia> g.content
+phase(0.1)
+
+julia> g.content.theta = 0.2
+0.2
+
+julia> g
+nqubits: 4, datatype: Complex{Float64}
+repeat on (1, 2, 3, 4)
+└─ phase(0.2)
+```
 """
 Base.repeat(n::Int, x::AbstractBlock, locs::Int...) =
     repeat(n, x, locs)

src/primitive/const_gate_gen.jl

@@ -42,3 +42,28 @@ Base.adjoint(::SGate) = Sdag
 Base.adjoint(::SdagGate) = S
 Base.adjoint(::TGate) = Tdag
 Base.adjoint(::TdagGate) = T
+
+# Docs
+"""
+    X
+    XGate{T} <: ConstantGate{1, T}
+
+Pauli X gate. `X` is the instance of `XGate`.
+"""
+X, XGate
+
+"""
+    Y
+    YGate{T}  <: ConstantGate{1, T}
+
+Pauli Y gate. `Y` is the instance of `YGate`.
+"""
+Y, YGate
+
+"""
+    Z
+    ZGate{T}  <: ConstantGate{1, T}
+
+Pauli Z gate. `Z` is the instance of `YGate`.
+"""
+Z, ZGate

src/primitive/general_matrix_gate.jl

@@ -26,6 +26,12 @@ GeneralMatrixBlock(m::AbstractMatrix) = GeneralMatrixBlock{log2i.(size(m))...}(m
     matblock(m::AbstractMatrix)
 
 Create a [`GeneralMatrixBlock`](@ref) with a matrix `m`.
+
+# Example
+
+```jldoctest
+
+```
 """
 matblock(m::AbstractMatrix) = GeneralMatrixBlock(m)
 

test/composite/chain.jl

@@ -9,6 +9,7 @@ using Test, YaoBase, YaoBlocks, YaoArrayRegister
     @test g.blocks == [kron(2, X, Y), kron(2, 1=>phase(0.1))]
     blks = [X, Y, Rx(0.3)]
     @test chsubblocks(g, blks) |> subblocks |> collect == blks
+    @test chsubblocks(chain(X, Y, Z), X for _ in 1:3) |> subblocks |> collect == [X, X, X]
 
     c1 = ChainBlock(put(5, 1=>X), put(5, 3=>Y))
     c2 = ChainBlock(put(5, 4=>X), put(5, 5=>Y))
@@ -22,18 +23,22 @@ using Test, YaoBase, YaoBlocks, YaoArrayRegister
     c = ChainBlock([X, Y])
     c[1] = put(1, 1=>X)
     @test c[1] == put(1, 1=>X)
-
-    list = []
-    push!(list, X)
-    @test chain(list) == chain(X)
-
-    @test chain(4, []) == chain(4)
 end
 
 @testset "test chain" begin
     @test chain(kron(1=>X), control(2, 1=>X))(4) |> nqubits == 4
     @test chain(control(4, 2, 1=>X), kron(1=>X)) |> nqubits == 4
     @test chain(control(4, 2, 1=>X), kron(4, 1=>X)) |> nqubits == 4
+
+    list = []
+    push!(list, X)
+    @test chain(list) == chain(X)
+
+    @test chain(4, []) == chain(4)
+    @test chain(X for _ in 1:3) == chain(X, X, X)
+    @test chain(put(1=>X))(4) == chain(put(4, 1=>X))
+    @test chain(put(1=>X), put(2=>X))(4) == chain(put(4, 1=>X), put(4, 2=>X))
+    @test chain()(4) == chain(4)
 end
 
 @testset "#15" begin
@@ -61,6 +66,46 @@ end
     r = rand_state(2)
     @test statevec(apply!(copy(r), g)) ≈ mat(g) * r.state
     apply!(copy(r), g)
+
+    @test chain(X, Y, Z, H)[2:4] == chain(Y, Z, H)
+
+    @testset "copy" begin
+        g = chain(phase(0.1))
+        g1 = copy(g)
+        g[1] = X
+        @test g1[1] == phase(0.1)
+    end
+
+    @testset "similar" begin
+        g = chain(X, Y, Z)
+        @test similar(g) == chain(1)
+    end
+
+    @testset "push!" begin
+        g = chain(2, put(1=>X))
+        push!(g, put(2=>X))
+        @test g == chain(2, put(1=>X), put(2=>X))
+    end
+
+    @testset "append!" begin
+        g1 = chain(X, Y, Z)
+        g2 = chain(Z, Z, Z)
+        @test append!(g1, g2) == chain(X, Y, Z, Z, Z, Z) == g1
+    end
+
+    @testset "prepend!" begin
+        g1 = chain(X, Y, Z)
+        g2 = chain(Z, Z, Z)
+        @test prepend!(g1, g2) == chain(Z, Z, Z, X, Y, Z) == g1
+    end
+
+    @testset "adjoint" begin
+        @test adjoint(chain(X, Y, Z, H)) == chain(H, Z, Y, X)
+    end
+
+    @testset "insert!" begin
+        @test insert!(chain(X, Y, Z), 2, H) == chain(X, H, Y, Z)
+    end
 end
 
 @testset "test iteration" begin

test/composite/composite.jl

@@ -35,3 +35,11 @@ end
 @testset "test pauli string" begin
     include("pauli_string.jl")
 end
+
+@testset "test single block chsubblocks" begin
+    @test chsubblocks(chain(X), Y) == chain(Y)
+    @test chsubblocks(kron(X), Y) == kron(Y)
+    @test chsubblocks(roll(X), Y) == roll(Y)
+    @test chsubblocks(prod(X), Y) == prod(Y)
+    @test chsubblocks(sum(X), Y) == sum(Y)
+end