Merge pull request #12 from QuantumBFS/fix-docs

Trying to get the docs compiling again

docs/Project.toml

@@ -2,8 +2,10 @@
 DocThemeIndigo = "8bac0ac5-51bf-41f9-885e-2bf1ac2bec5f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 FLOYao = "6d9310a3-f1d0-41b7-8edb-11c1cf57cd2d"
+Yao = "5872b779-8223-5990-8dd0-5abbb0748c8c"
 YaoAPI = "0843a435-28de-4971-9e8b-a9641b2983a8"
 YaoArrayRegister = "e600142f-9330-5003-8abb-0ebd767abc51"
 
 [compat]
 DocThemeIndigo = "0.1.1"
+Documenter = "1"

docs/make.jl

@@ -17,13 +17,14 @@ const PAGES = [
 ]
 
 makedocs(;
-    modules = [FLOYao,YaoAPI],
+    modules = [FLOYao,],
     format = Documenter.HTML(
         prettyurls = !("local" in ARGS),
         canonical="https://QuantumBFS.github.io/FLOYao.jl",
         assets=String[indigo],
     ),
     pages = PAGES,
+    checkdocs = :exports,
     repo = "https://github.com/QuantumBFS/FLOYao.jl",
     sitename = "FLOYao.jl",
 )

docs/src/features/features.md

@@ -30,20 +30,31 @@ FLOYao.product_state!
 
 ## Applying gates
 Application of [Supported gates](@ref) to [`MajoranaReg`](@ref)'s works 
-as it does in `Yao.jl`
+as it does in [`Yao.jl`](https://docs.yaoquantum.org/stable/man/blocks.html#Base.:|%3E-Tuple{AbstractRegister,%20AbstractBlock})
 
-```@docs
-YaoAPI.apply! 
+```julia
+reg = FLOYao.zero_state(2)
+gate = put(2, 1 => X)
+
+# using apply!
+apply!(reg, gate)
+
+# or using the pipe syntax
+reg |> gate
+
+# or the non-mutating version
+result = apply(reg, gate)
 ```
 
 ## Measuring expectation values
 The same goes measuring expectation values 
 ```@docs
-expect 
+expect
 ```
 where (for now) `op` is restricted to be an observable quadratic in the 
-Majorana operators (see [Known restrictions](@ref)).
-
+Majorana operators (see [Known restrictions](@ref)). 
+See the section about [`expect`](https://docs.yaoquantum.org/stable/man/blocks.html#YaoAPI.expect-Tuple{AbstractBlock,%20DensityMatrix})
+in the `Yao.jl` documentation for the details.
 
 ## Sampling
 Samples in the computational basis can be obtained with the same functions as 
@@ -54,6 +65,22 @@ measure(::MajoranaReg)
 measure!(::MajoranaReg)
 ```
 
+## Fidelities and bitstring probabilities
+Fidelities between two `MajoranaReg`s can be computed the same way as in 
+`Yao.jl`:
+
+```@docs
+fidelity(::MajoranaReg, ::MajoranaReg)
+```
+
+Under the hood this function uses a non-exported function to compute the 
+probability of obtaining a given `bit_string` as an output when measuring in 
+the computational basis:
+
+```@docs
+FLOYao.bitstring_probability
+```
+
 ## Non-exported functions
 The following functions are not exported and not really needed for the 
 functionality of `FLOYao`, but can be useful for debugging.

docs/src/index.md

@@ -1,17 +1,9 @@
 # FLOYao
 
-A [Yao.jl](https://github.com/QuantumBFS/Yao.jl) backend to efficiently simulated
-fermionic linear optics (FLO) circuits in  based on
-[Classical simulation of noninteracting-fermion quantum circuits](https://arxiv.org/abs/quant-ph/0108010)
-and [Disorder-assisted error correction in Majorana chains](https://arxiv.org/abs/1108.3845).
-FLO circuits are a class of quantum circuits that are closely related to
-non-interacting fermions and can be efficiently simulated on classical
-computers, similar to the way Clifford circuits can be efficiently classically
-simulated, as is done in [YaoClifford.jl](https://github.com/QuantumBFS/YaoClifford.jl).
-
-A quick introduction to fermionic linear optics circuits is found in
-[Background](@ref background) section and a more in-depth introduction in e.g. the two
-papers linked above.
+
+```@docs
+FLOYao.FLOYao
+```
 
 ## Installation
 `FLOYao` can be simply installed from the REPL via

docs/src/known_restrictions.md

@@ -5,9 +5,9 @@ So far, `FLOYao` only supports expectation values of observables that are sums o
 Majorana operators. But in general, one can use [Wick's theorem](https://en.wikipedia.org/wiki/Wick%27s_theorem)
 to calculate the expectation values of expressions of the form 
 ```math
-    ⟨O⟩ = ⟨\Omega |U^† O U|\Omega ⟩
+    ⟨O⟩ = ⟨Ω|U^† O U|Ω⟩
 ```
-where $|Ω⟩ = |0 ⋯ 0⟩$ is the all zero stat, $O$ a string of Majorana operators
+where $|Ω⟩ = |0 ⋯ 0⟩$ is the all zero state, $O$ a string of Majorana operators
 and $U$ a FLO unitary. Thus, using linearity of the expectation value, it is
 possible to efficiently calculate the expectation value of any observable that
 can be expanded in a sum of polynomially (in the number of qubits) many

docs/src/vqe_example.md

@@ -36,7 +36,7 @@ hamiltonian = T + U
 summary(hamiltonian)
 
 # output
-"Add{2}"
+"YaoBlocks.Add{2}"
 ```
 
 

src/FLOYao.jl

@@ -16,10 +16,24 @@
 =#
 
 """
-Support for fermionic linear optics circuits in Yao.jl. This is broadly based
-on [Classical simulation of noninteracting-fermion quantum circuits](https://arxiv.org/abs/quant-ph/0108010),
-but everything you need to know for the exact mathematical details of this
-implementation is also found in my wiki in `simulating-fermionic-linear-optic-circuits`.
+A [Yao.jl](https://github.com/QuantumBFS/Yao.jl) backend to efficiently simulate
+fermionic linear optics (FLO) circuits  based on
+[Classical simulation of noninteracting-fermion quantum circuits](https://arxiv.org/abs/quant-ph/0108010)
+and [Disorder-assisted error correction in Majorana chains](https://arxiv.org/abs/1108.3845).
+FLO circuits are a class of quantum circuits that are closely related to
+non-interacting fermions and can be efficiently simulated on classical
+computers, similar to the way Clifford circuits can be efficiently classically
+simulated, as is done in [YaoClifford.jl](https://github.com/QuantumBFS/YaoClifford.jl).
+
+The goal of `FLOYao.jl` is that if you have code written in `Yao.jl` that only 
+uses [FLO gates](https://quantumbfs.github.io/FLOYao.jl/stable/supported_gates/)
+and other primitives that are efficiently simulatable in polynomial time and 
+space, that you can simply replace your `AbstractArrayReg` with a `MajoranaReg`
+and run exactly the same simulation, with the same code but exponentially faster.
+
+A brief introduction to fermionic linear optics circuits is found in the 
+[Documentation](https://yaoquantum.org/FLOYao.jl/stable/background/) and a more
+in-depth introduction in e.g. the two papers linked above.
 """
 module FLOYao
 

src/expect.jl

@@ -42,6 +42,27 @@ function majorana_expect(block::AbstractMatrix, locs, reg::MajoranaReg)
     return (- expval - offset_expval) / 4
 end
 
+# a little hack to attach a docstring to `expect(::AbstractBlock, ::MajoranaReg)`
+# without actually implementing it
+"""
+    expect(op::AbstractBlock, reg::MajoranaReg)
+    expect(op::AbstractBlock, (reg => circuit)::Pair{<:MajoranaReg,<:AbstractBlock})
+
+Get the expectation value of an operator, the second parameter can be a
+register `reg` or a pair of input register and circuit `reg => circuit`.
+
+    expect'(op::AbstractBlock, reg => circuit::) -> Pair{<:MajoranaReg,<:AbstractVector}
+    expect'(op::AbstractBlock, reg::MajoranaReg) -> MajoranaReg
+
+Obtain the gradient with respect to registers and circuit parameters. For pair
+input, the second return value is a pair of `gψ => gparams`, with `gψ` the gradient
+of input state and `gparams` the gradients of circuit parameters. For register
+input, the return value is a register.
+"""
+function Yao.expect(op::AbstractBlock, reg::MajoranaReg)
+    invoke(Yao.expect, Yao.expect, Tuple{AbstractBlock, AbstractRegister}, op, reg)
+end
+
 for BT in [:AbstractAdd, :(KronBlock{2}), :(PutBlock{2,1,ZGate})]
     @eval function Yao.expect(op::$BT, reg::MajoranaReg)
         YaoBlocks._check_size(reg, op)
@@ -74,6 +95,20 @@ function bitstring_probability(reg::MajoranaReg{T}, bit_string::DitStr{2,N,ST})
     return p > zero(T) ? p : zero(T) # floating point issues can cause very small probabilities to get negative.
 end
 
+"""
+    fidelity(reg1::MajoranaReg, reg2::MajoranaReg)
+
+The fidelity ``|⟨ψ|φ⟩|`` between the FLO states ``|ψ⟩`` and ``|φ⟩`` defined
+by `reg1` and `reg2`.
+
+!!! note
+    This definition differs from the standard definition ``|⟨φ|ψ⟩|²`` by a square 
+    root, but is consistent with the one used in `Yao.jl`
+
+!!! note
+    Computing gradients of the fidelity via `fidelity'(pair_or_reg1, pair_or_reg2)`
+    is not yet supported for `MajoranaReg`s.
+"""
 function Yao.fidelity(reg1::MajoranaReg{T1}, reg2::MajoranaReg{T2}) where {T1,T2}
     T = promote_type(T1, T2)
     nq = nqubits(reg1)

src/measure.jl

@@ -37,7 +37,8 @@ end
 Updates the covariance matrix `M`, given that the `i`th qubit was measured
 in the state `ni` with probability `pi`.
 
-# Note: After this procedure only the entries M[p,q] with 2i-1 < p < q
+# Warning
+After this procedure only the entries M[p,q] with 2i-1 < p < q
 will be correct. This is sufficient to calculate measurement probabilities
 for j > i.
 """