fixes to Purify2to1 and many small improvements to make test writting…

… easier (#28)

Project.toml

@@ -1,10 +1,11 @@
 name = "QuantumSavory"
 uuid = "2de2e421-972c-4cb5-a0c3-999c85908079"
 authors = ["Stefan Krastanov <[email protected]>"]
-version = "0.3.0"
+version = "0.3.1"
 
 [deps]
 ConcurrentSim = "6ed1e86c-fcaf-46a9-97e0-2b26a2cdb499"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 IterTools = "c8e1da08-722c-5040-9ed9-7db0dc04731e"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
@@ -29,6 +30,7 @@ QuantumSavoryMakie = "Makie"
 
 [compat]
 ConcurrentSim = "1.1"
+DocStringExtensions = "0.9"
 Graphs = "1.7.3"
 IterTools = "1.4.0"
 Makie = "0.19"
@@ -38,7 +40,7 @@ QuantumClifford = "0.8"
 QuantumInterface = "0.3.0"
 QuantumOptics = "1.0.5"
 QuantumOpticsBase = "0.4"
-QuantumSymbolics = "0.2.3"
+QuantumSymbolics = "0.2.4"
 Reexport = "1.2.2"
 ResumableFunctions = "0.6.1"
 julia = "1.9"

docs/Project.toml

@@ -14,6 +14,7 @@ Quantikz = "b0d11df0-eea3-4d79-b4a5-421488cbf74b"
 QuantumClifford = "0525e862-1e90-11e9-3e4d-1b39d7109de1"
 QuantumOptics = "6e0679c1-51ea-5a7c-ac74-d61b76210b0c"
 QuantumSavory = "2de2e421-972c-4cb5-a0c3-999c85908079"
+QuantumSymbolics = "efa7fd63-0460-4890-beb7-be1bbdfbaeae"
 ResumableFunctions = "c5292f4c-5179-55e1-98c5-05642aab7184"
 Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"

docs/make.jl

@@ -8,11 +8,12 @@ using QuantumSavory
 DocMeta.setdocmeta!(QuantumSavory, :DocTestSetup, :(using QuantumSavory); recursive=true)
 
 function main()
-    bib = CitationBibliography(joinpath(@__DIR__,"src/references.bib"))
+    bib = CitationBibliography(joinpath(@__DIR__,"src/references.bib"), style=:authoryear)
     makedocs(
     bib,
     doctest = false,
     clean = true,
+    # strict = Documenter.except(:missing_docs), TODO
     sitename = "QuantumSavory.jl",
     format = Documenter.HTML(
         assets=["assets/init.js"]
@@ -46,6 +47,7 @@ function main()
     "References" => [
         "references.md",
         "API" => "API.md",
+        "CircuitZoo API" => "API_CircuitZoo.md",
         "Bibliography" => "bibliography.md",
     ],
     ]

docs/src/API_CircuitZoo.md

@@ -0,0 +1,17 @@
+# Available Circuits
+
+```@raw html
+<style>
+    .content table td {
+        padding-top: 0 !important;
+        padding-bottom: 0 !important;
+    }
+</style>
+```
+
+## Autogenerated API list for `QuantumClifford.CircuitZoo`
+
+```@autodocs
+Modules = [QuantumSavory.CircuitZoo]
+Private = false
+```

docs/src/API_Symbolics.md

@@ -0,0 +1,19 @@
+# QuantumSymbolics.jl reference
+
+You can also consult the [complete `QuantumSymbolics.jl` documentation](https://quantumsavory.github.io/QuantumSymbolics.jl/stable/).
+
+```@raw html
+<style>
+    .content table td {
+        padding-top: 0 !important;
+        padding-bottom: 0 !important;
+    }
+</style>
+```
+
+## Autogenerated API list for `QuantumSymbolics`
+
+```@autodocs
+Modules = [QuantumSymbolics]
+Private = false
+```

docs/src/howto/firstgenrepeater/firstgenrepeater.md

@@ -189,7 +189,7 @@ end
 </details>
 ```
 
-Notice that the entangler uses the [`initialize!`](@ref) function to set the state of certain registers, but we never need to explicitly construct the numerical representation of these kets. Rather, we use the [symbolic algebra system](@ref Symbolics) of `QuantumClifford.jl`, and let the simulator automatically convert the symbolic expression into numerical density matrices. This conversion was governed by the choice of `representation = QuantumOpticsRepr`. Here is one possible symbolic definition of a `noisy_pair`:
+Notice that the entangler uses the [`initialize!`](@ref) function to set the state of certain registers, but we never need to explicitly construct the numerical representation of these kets. Rather, we use the symbolic algebra system of [`QuantumSymbolics.jl`](https://github.com/QuantumSavory/QuantumSymbolics.jl), and let the simulator automatically convert the symbolic expression into numerical density matrices. This conversion was governed by the choice of `representation = QuantumOpticsRepr`. Here is one possible symbolic definition of a `noisy_pair`:
 
 ```julia
 const perfect_pair = (Z1⊗Z1 + Z2⊗Z2) / sqrt(2)

docs/src/index.md

@@ -8,7 +8,7 @@ end
 
 A multi-formalism simulator for noisy quantum communication and computation hardware with support for symbolic algebra, multiple simulation backends, a variety of noise models, discrete event simulation, optimization, and visualization.
 
-We are also preparing a [getting started manual](/manual).
+We are also preparing a [getting started manual](@ref manual).
 
 The rest of the documentation is [structured](https://diataxis.fr/) as follows:
 

docs/src/manual.md

@@ -1,4 +1,4 @@
-# Manual
+# [Manual](@id manual)
 
 ```@meta
 DocTestSetup = quote

docs/src/references.bib

@@ -47,7 +47,7 @@ @article{wilde2009logical
 
 % The basis of the tableaux algorithm
 
-@article{gottesman1998heisenberg,
+@inproceedings{gottesman1998heisenberg,
   title={The Heisenberg representation of quantum computers},
   author={Gottesman, Daniel},
   booktitle={International Conference on Group Theoretic Methods in Physics},
@@ -94,7 +94,7 @@ @article{bravyi2020hadamard
   doi={10.1109/TIT.2021.3081415}
 }
 
-@article{berg2020simple,
+@inproceedings{berg2020simple,
   title={A simple method for sampling random Clifford operators},
   author={Van Den Berg, Ewout},
   booktitle={2021 IEEE International Conference on Quantum Computing and Engineering (QCE)},
@@ -138,11 +138,12 @@ @article{audenaert2005entanglement
   doi={10.1088/1367-2630/7/1/170}
 }
 
-@article{gottesman1997stabilizer,
+@phdthesis{gottesman1997stabilizer,
   title={Stabilizer codes and quantum error correction},
   author={Gottesman, Daniel},
   year={1997},
   publisher={California Institute of Technology},
+  school={California Institute of Technology},
   url={https://arxiv.org/abs/quant-ph/9705052}
 }
 
@@ -174,7 +175,7 @@ @article{nahum2017quantum
   year = {2017}
 }
 
-@article{hein2006entanglement,
+@misc{hein2006entanglement,
 	title = {Entanglement in Graph States and its Applications},
 	url = {http://arxiv.org/abs/quant-ph/0602096},
 	journaltitle = {arXiv preprint arXiv:quant-ph/0602096},

docs/src/register_interface.md

@@ -78,7 +78,7 @@ Applying an `operation` to the qubits referred to by the sequence of [`RegRef`](
 
 Calls [`uptotime!`](@ref) in order to update any [`AbstractBackground`](@ref) properties.
 
-Calls [`subsystemcompose!`](@ref) in order to make one big state. Then goes to `apply!(state, subsystem_indices, operatin; time)`.
+Calls [`subsystemcompose`](@ref) in order to make one big state. Then goes to `apply!(state, subsystem_indices, operatin; time)`.
 
 #### `apply!(state, subsystem_indices, operation; time)`
 
@@ -100,7 +100,7 @@ flowchart TB
   subgraph TOP [lower from registers to states]
     direction LR
     B1["<code>uptotime!</code>"]
-    B2["<code>subsystemcompose!</code>"]
+    B2["<code>subsystemcompose</code>"]
     B1 --> B2
   end
   C["<code>apply!(state, subsystem_indices, operation; time)</code>"]
@@ -138,7 +138,7 @@ Calculate the value of an observable on the state in the sequence of [`RegRef`](
 
 Calls [`uptotime!`](@ref) in order to update any [`AbstractBackground`](@ref) properties.
 
-Calls [`subsystemcompose!`](@ref) in order to make one big state. Then goes to `observable(state, subsystem_indices, obs; time)`.
+Calls [`subsystemcompose`](@ref) in order to make one big state. Then goes to `observable(state, subsystem_indices, obs; time)`.
 
 #### `observable(state, subsystem_indices, obs; time)`
 
@@ -160,7 +160,7 @@ flowchart TB
   subgraph TOP [lower from registers to states]
     direction LR
     B1["<code>uptotime!</code>"]
-    B2["<code>subsystemcompose!</code>"]
+    B2["<code>subsystemcompose</code>"]
     B1 --> B2
   end
   C["<code>observable(state, subsystem_indices, obs; time)</code>"]

src/CircuitZoo/CircuitZoo.jl

@@ -1,6 +1,9 @@
 module CircuitZoo
 
 using QuantumSavory
+using DocStringExtensions
+
+export Purify2to1
 
 abstract type AbstractCircuit end
 
@@ -20,7 +23,79 @@ function (::EntanglementSwap)(localL, remoteL, lacalR, remoteR)
     xmeas, zmeas
 end
 
+"""
+$TYPEDEF
+
+## Fields:
+
+$FIELDS
+
+A simple purification circuit sacrificing a Bell pair to produce another.
+The circuit is parameterized by a single `leaveout` symbol argument
+which specifies which of the three possible Pauli errors are to be left undetected.
+A simple purificaiton circuit is not capable of detecting all errors.
+
+If an error was detected, the circuit returns `false` and the state is reset.
+If no error was detected, the circuit returns `true`.
+
+The sacrificial qubits are removed from the register.
+
+```jldoctest
+julia> a = Register(2)
+       b = Register(2)
+       bell = (Z₁⊗Z₁+Z₂⊗Z₂)/√2
+       initialize!((a[1], b[1]), bell)
+       initialize!((a[2], b[2]), bell);
+
+julia> Purify2to1(:X)(a[1], b[1], a[2], b[2])
+true
+
+julia> observable((a[1], b[1]), projector(bell))
+1.0 + 0.0im
+```
+
+However, an error might have occurred on the initial state. If the error is detectable,
+the `Purify2to1` circuit will return `false` and the state will be reset.
+
+```jldoctest
+julia> a = Register(2)
+       b = Register(2)
+       bell = (Z₁⊗Z₁+Z₂⊗Z₂)/√2
+       initialize!((a[1], b[1]), bell)
+       initialize!((a[2], b[2]), bell)
+       apply!(a[1], Z);
+
+julia> Purify2to1(:X)(a[1], b[1], a[2], b[2])
+false
+
+julia> a
+Register with 2 slots: [ Qubit | Qubit ]
+  Slots:
+    nothing
+    nothing
+```
+
+In some cases the error might not be detectable. In that case, the `Purify2to1` circuit
+does return `true`, but as you can see below, the state is not what we would expect from
+a successful purification.
+
+```jldoctest
+julia> a = Register(2)
+       b = Register(2)
+       bell = (Z₁⊗Z₁+Z₂⊗Z₂)/√2
+       initialize!((a[1], b[1]), bell)
+       initialize!((a[2], b[2]), bell)
+       apply!(a[1], X);
+
+julia> Purify2to1(:X)(a[1], b[1], a[2], b[2])
+true
+
+julia> observable((a[1], b[1]), projector(bell))
+0.0 + 0.0im
+```
+"""
 struct Purify2to1 <: AbstractCircuit
+    """A symbol specifying which of the three Pauli errors to leave undetectable."""
     leaveout::Symbol
     function Purify2to1(leaveout)
         if leaveout ∉ (:X, :Y, :Z)
@@ -38,18 +113,18 @@ struct Purify2to1 <: AbstractCircuit
 end
 
 function (circuit::Purify2to1)(purifiedL,purifiedR,sacrificedL,sacrificedR)
-    gate, basis, parity = if circuit.leaveout==:X
-        CNOT, σˣ, 0
+    gate, basis = if circuit.leaveout==:X
+        CNOT, σˣ
     elseif circuit.leaveout==:Z
-        CPHASE, σˣ, 0
+        XCZ, σᶻ
     elseif circuit.leaveout==:Y
-        YCX, σʸ, 1
+        ZCY, σʸ
     end
     apply!((sacrificedL,purifiedL),gate)
     apply!((sacrificedR,purifiedR),gate)
     measa = project_traceout!(sacrificedL, basis)
     measb = project_traceout!(sacrificedR, basis)
-    success = measa ⊻ measb == parity
+    success = measa == measb
     if !success
         traceout!(purifiedL)
         traceout!(purifiedR)