Merge branch 'master' into hana_doc

QuantumSavory · Mar 1, 2025 · 42d3c09 · 42d3c09
2 parents abf95df + 51b9bbd
commit 42d3c09
Show file tree

Hide file tree

Showing 85 changed files with 1,107 additions and 292 deletions.
diff --git a/.github/workflows/benchmark-comment.yml b/.github/workflows/benchmark-comment.yml
@@ -26,7 +26,7 @@ jobs:
       - uses: actions/checkout@v4
 
       # restore records from the artifacts
-      - uses: dawidd6/action-download-artifact@v6
+      - uses: dawidd6/action-download-artifact@v8
         with:
           workflow: benchmark.yml
           name: performance-tracking

diff --git a/.gitignore b/.gitignore
@@ -2,4 +2,5 @@ Manifest.toml
 build
 .gitignore
 ROADMAP.md
-coverage
+coverage
+*.cov
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,8 @@
 ## v0.5.1-dev
 
 - Add `classical_delay` and `quantum_delay` as keyword arguments to the `RegisterNet` constructor to set a default global network edge latency.
+- `onchange_tag` now permits a protocol to wait for any change to the tag metadata. Implemented thanks to the new `AsymmetricSemaphore`, a resource object that allows multiple processes to wait for an update.
+- Plots of networks can now overlay real-world maps (see `generate_map`).
 
 ## v0.5.0 - 2024-10-16
 

diff --git a/Project.toml b/Project.toml
@@ -27,27 +27,30 @@ SumTypes = "8e1ec7a9-0e02-4297-b0fe-6433085c89f2"
 
 [weakdeps]
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
+GeoMakie = "db073c08-6b98-4ee5-b6a4-5efafb3259c6"
 
 [extensions]
+QuantumSavoryGeoMakie = "GeoMakie"
 QuantumSavoryMakie = "Makie"
 
 [compat]
 Combinatorics = "1"
 ConcurrentSim = "1.5"
 Distributions = "0.25.90"
 DocStringExtensions = "0.9"
+GeoMakie = "0.7.8"
 Graphs = "1.9"
 IterTools = "1.4.0"
 LinearAlgebra = "1"
-Makie = "0.20, 0.21"
+Makie = "0.20, 0.21, 0.22"
 NetworkLayout = "0.4.4"
 PrecompileTools = "1"
 Printf = "1"
 QuantumClifford = "0.9.9"
 QuantumInterface = "0.3.5"
 QuantumOptics = "1.1.0"
 QuantumOpticsBase = "0.5.3"
-QuantumSymbolics = "0.4.3"
+QuantumSymbolics = "0.4.8"
 Random = "1"
 Reexport = "1.2.2"
 ResumableFunctions = "1"

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -5,6 +5,7 @@ Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
+GeoMakie = "db073c08-6b98-4ee5-b6a4-5efafb3259c6"
 GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
@@ -13,6 +14,7 @@ PrettyPrint = "8162dcfd-2161-5ef2-ae6c-7681170c5f98"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Quantikz = "b0d11df0-eea3-4d79-b4a5-421488cbf74b"
 QuantumClifford = "0525e862-1e90-11e9-3e4d-1b39d7109de1"
+QuantumInterface = "5717a53b-5d69-4fa3-b976-0bf2f97ca1e5"
 QuantumOptics = "6e0679c1-51ea-5a7c-ac74-d61b76210b0c"
 QuantumOpticsBase = "4f57444f-1401-5e15-980d-4471b28d5678"
 QuantumSavory = "2de2e421-972c-4cb5-a0c3-999c85908079"

diff --git a/docs/make.jl b/docs/make.jl
@@ -4,9 +4,10 @@ push!(LOAD_PATH,"../src/")
 using Documenter
 using DocumenterCitations
 using QuantumSavory
-using QuantumSavory.ProtocolZoo # TODO is this the correct place to place this to ensure cross_references work
+using QuantumSavory.StatesZoo, QuantumSavory.ProtocolZoo, QuantumSavory.CircuitZoo
+using QuantumInterface
 
-DocMeta.setdocmeta!(QuantumSavory, :DocTestSetup, :(using QuantumSavory); recursive=true)
+DocMeta.setdocmeta!(QuantumSavory, :DocTestSetup, :(using QuantumSavory, QuantumSavory.StatesZoo, QuantumSavory.ProtocolZoo, QuantumSavory.CircuitZoo); recursive=true)
 
 function main()
     bib = CitationBibliography(joinpath(@__DIR__,"src/references.bib"), style=:authoryear)
@@ -19,7 +20,7 @@ function main()
     format = Documenter.HTML(
         assets=["assets/init.js"]
     ),
-    modules = [QuantumSavory],
+    modules = [QuantumSavory, QuantumSavory.StatesZoo, QuantumSavory.ProtocolZoo, QuantumSavory.CircuitZoo, QuantumInterface],
     authors = "Stefan Krastanov",
     pages = [
     "QuantumSavory.jl" => "index.md",
@@ -36,13 +37,17 @@ function main()
     ],
     "How-To Guides" => [
         "howto.md",
-        "1st-gen Repeater" => "howto/firstgenrepeater/firstgenrepeater.md",
-        "1st-gen Repeater (Clifford formalism)" => "howto/firstgenrepeater/firstgenrepeater-clifford.md",
+        "1st-gen Repeater - low level implementation" => "howto/firstgenrepeater/firstgenrepeater.md",
+        "1st-gen Repeater - Clifford formalism" => "howto/firstgenrepeater/firstgenrepeater-clifford.md",
+        "1st-gen Repeater - simpler implementation" => "howto/firstgenrepeater_v2/firstgenrepeater_v2.md",
+        "Congestion on a Repeater Chain" => "howto/congestionchain/congestionchain.md",
         "Cluster States in Atomic Memories" => "howto/colorcentermodularcluster/colorcentermodularcluster.md",
+        "Entanglement Switch" => "howto/simpleswitch/simpleswitch.md",
     ],
     "Tutorials" => [
         "tutorial.md",
-        "Gate duration" => "tutorial/noninstantgate.md",
+        "Gate Duration" => "tutorial/noninstantgate.md",
+        "State Explorer" => "tutorial/state_explorer.md",
         #"Message queues" => "tutorial/message_queues.md", TODO
         #"Depolarization and Pauli Noise" => "tutorial/depolarization_and_pauli.md", TODO
     ],

diff --git a/docs/outdated/depolarization_and_pauli.md b/docs/outdated/depolarization_and_pauli.md
@@ -1,12 +1,5 @@
 # Depolarization and Pauli Noise
 
-```@meta
-DocTestSetup = quote
-    using QuantumSavory
-    using CairoMakie
-end
-```
-
 TODO not finished and not included
 
 Multi-qubit partial depolarization is the same as multi-qubit Pauli noise where each multi-qubit Pauli error has equal probability independent of its (Hamming) weight.

diff --git a/docs/outdated/message_queues.md b/docs/outdated/message_queues.md
@@ -1,12 +1,5 @@
 # Message passing and queues
 
-```@meta
-DocTestSetup = quote
-    using QuantumSavory
-    using CairoMakie
-end
-```
-
 !!! warning
 
     This section is rather low-level, created before a lot of user-friendly tools were added.
@@ -219,4 +212,3 @@ The horizontal axis is simulation time. We plot the periods during which one of
 - node 2 is waiting to receive a message that the system reset happened.
 
 As you can see, node 1 can start measurements before node 2 has heard that the system reset has happened, due to the communication delay.
-
diff --git a/docs/src/API_CircuitZoo.md b/docs/src/API_CircuitZoo.md
@@ -1,4 +1,4 @@
-# Available Circuits
+# [Predefined Quantum Circuits](@id Predefined-Quantum-Circuits)
 
 ```@raw html
 <style>
@@ -9,6 +9,8 @@
 </style>
 ```
 
+The submodule `QuantumSavory.CircuitZoo` provides reusable common quantum circuits.
+
 ## Autogenerated API list for `QuantumSavory.CircuitZoo`
 
 ```@autodocs

diff --git a/docs/src/API_Interface.md b/docs/src/API_Interface.md
@@ -0,0 +1,25 @@
+# QuantumInterface.jl reference
+
+`QuantumInterface.jl` is a base package meant to define common APIs used by many independent QIS packages.
+
+```@raw html
+<style>
+    .content table td {
+        padding-top: 0 !important;
+        padding-bottom: 0 !important;
+    }
+</style>
+```
+
+## Autogenerated API list for `QuantumInterface`
+
+```@autodocs
+Modules = [QuantumInterface]
+Private = false
+```
+
+```@docs
+QuantumInterface.AbstractRepresentation
+QuantumInterface.CliffordRepr
+QuantumInterface.QuantumOpticsRepr
+```
diff --git a/docs/src/API_ProtocolZoo.md b/docs/src/API_ProtocolZoo.md
@@ -1,4 +1,4 @@
-# Available Protocols
+# Predefined Networking Protocols
 
 ```@raw html
 <style>
@@ -9,6 +9,8 @@
 </style>
 ```
 
+The submodule `QuantumSavory.ProtocolZoo` provides models for many common quantum networking protocols, including the details of their discrete event scheduling and simulation.
+
 ## Autogenerated API list for `QuantumSavory.ProtocolZoo`
 
 ```@autodocs

diff --git a/docs/src/API_StatesZoo.md b/docs/src/API_StatesZoo.md
@@ -1,4 +1,4 @@
-# Available States
+# [Predefined Models of Quantum States](@id Predefined-Models-of-Quantum-States)
 
 ```@raw html
 <style>
@@ -9,6 +9,8 @@
 </style>
 ```
 
+The submodule `QuantumSavory.StatesZoo` provides models for many frequently used quantum states.
+
 ## Autogenerated API list for `QuantumSavory.StatesZoo`
 
 ```@autodocs

diff --git a/docs/src/explanations.md b/docs/src/explanations.md
@@ -1,11 +1,5 @@
 # Explanations
 
-```@meta
-DocTestSetup = quote
-    using QuantumSavory
-end
-```
-
 This section covers how is the library structured, what are its conventions, and why were they decided upon.
 
 You probably want to cover the:

diff --git a/docs/src/howto.md b/docs/src/howto.md
@@ -1,10 +1,4 @@
-# How-To Guides 
-
-```@meta
-DocTestSetup = quote
-    using QuantumSavory
-end
-```
+# How-To Guides
 
 "HowTo"s are fully fleshed out examples of how to use `QuantumSavory` to set up a complete simulation of a system of interest. They do not go into details of how the library is structured internally and do not provide in-depth discussion of APIs, rather they showcase idiomatic use of the library.
 

diff --git a/docs/src/howto/colorcentermodularcluster/colorcentermodularcluster.md b/docs/src/howto/colorcentermodularcluster/colorcentermodularcluster.md
@@ -1,10 +1,7 @@
 # [Cluster State on Color Centers](@id Cluster-State-on-Color-Centers)
 
-```@meta
-DocTestSetup = quote
-    using QuantumSavory
-end
-```
+!!! info "TODO Unfinished"
+    This page is unfinished!
 
 [Cluster states](https://en.wikipedia.org/wiki/Cluster_state) are highly entangled state of qubits useful as a [computational resource](https://en.wikipedia.org/wiki/One-way_quantum_computer).
 The cluster state is also a [graph state](https://en.wikipedia.org/wiki/Graph_state) where the graph has a 2D grid topology.
@@ -15,6 +12,10 @@ One interesting hardware implementation involves entangling a large number of co
 
 We will build a simulator for such a piece of hardware.
 Each node will be a register of one electron spin for networking and one nuclear spin in which the actual long-term entanglement is "stored".
+
+!!! info "Low Level Implementation"
+    This is a very low-level implementation. You would be better of using already implemented reusable protocols like [`EntanglerProt`](https://qs.quantumsavory.org/dev/API_ProtocolZoo/#QuantumSavory.ProtocolZoo.EntanglerProt). On the other hand, the setup here is a simple way to learn about making discrete event simulations without depending on a lot of extra library functionality and opaque black boxes.
+
 The visualization below shows an example of the state being generated, together with tracking the state of various locks and other metadata that needs to be tracked.
 
 ```@raw html
@@ -40,11 +41,10 @@ Moreover, behind the scenes `QuantumSavory.jl` will use:
 
 The user does not need to know much about these libraries, but if they wish, it is easy for them to peek behind the scenes and customize their use.
 
-!!! warning
+Below we embed a live version of the simulation (hosted at [areweentangledyet.com/colorcentermodularcluster/](https://areweentangledyet.com/colorcentermodularcluster/)):
 
-    This example is not yet well documented, nor is it modeling all of the noise processes of interest in this hardware. The code is not particularly clean yet either.
-
-## Full Code
+```@raw html
+<iframe src="https://areweentangledyet.com/colorcentermodularcluster/" style="height:850px;width:1250px;"></iframe>
+```
 
-The entirety of the code necessary for reproducing these results is in the
-[examples folder of the `QuantumSavory.jl` repository](https://github.com/QuantumSavory/QuantumSavory.jl/tree/master/examples/colorcentermodularcluster).
+The source code is in the [`examples/colorcentermodularcluster`](https://github.com/QuantumSavory/QuantumSavory.jl/tree/master/examples/colorcentermodularcluster) folder.
diff --git a/docs/src/howto/congestionchain/congestionchain.md b/docs/src/howto/congestionchain/congestionchain.md
@@ -0,0 +1,17 @@
+# A Study of Congestions over a Repeater Chain
+
+!!! info "TODO Unfinished"
+    This page is unfinished!
+
+A simple example to study congestion on a chain of quantum repeaters.
+
+!!! info "Low Level Implementation"
+    This is a very low-level implementation. You would be better of using already implemented reusable protocols like [`EntanglerProt`](https://qs.quantumsavory.org/dev/API_ProtocolZoo/#QuantumSavory.ProtocolZoo.EntanglerProt). On the other hand, the setup here is a simple way to learn about making discrete event simulations without depending on a lot of extra library functionality and opaque black boxes.
+
+Below we embed a live version of the simulation (hosted at [areweentangledyet.com/congestionchain/](https://areweentangledyet.com/congestionchain/)):
+
+```@raw html
+<iframe src="https://areweentangledyet.com/congestionchain/" style="height:800px;width:850px;"></iframe>
+```
+
+The source code is in the [`examples/congestionchain`](https://github.com/QuantumSavory/QuantumSavory.jl/tree/master/examples/congestionchain) folder.
diff --git a/docs/src/howto/congestionchain/congestionchain.mp4 b/docs/src/howto/congestionchain/congestionchain.mp4
diff --git a/docs/src/howto/congestionchain/congestionchain_stats_vs_chainlength.png b/docs/src/howto/congestionchain/congestionchain_stats_vs_chainlength.png
diff --git a/docs/src/howto/firstgenrepeater/firstgenrepeater-clifford.md b/docs/src/howto/firstgenrepeater/firstgenrepeater-clifford.md
@@ -1,11 +1,5 @@
 # Clifford Simulations of First Generation Quantum Repeater
 
-```@meta
-DocTestSetup = quote
-    using QuantumSavory
-end
-```
-
 Here we will simulate a quantum repeater by employing a noisy Clifford circuit simulator.
 
 Be sure to check out the more detailed tutorial on [wavefunction simulations of First Generation Quantum Repeater](@ref First-Generation-Quantum-Repeater) before proceeding with this one.
@@ -63,7 +57,5 @@ We can run the either simulation multiple times in order to compare the results
 
 ![Comparison Against a Wavefunction-based Simulations](./firstgenrepeater-09.formalisms.png)
 
-## Full Code
 
-The entirety of the code necessary for reproducing these results is in the
-[examples folder of the `QuantumSavory.jl` repository](https://github.com/QuantumSavory/QuantumSavory.jl/tree/master/examples/firstgenrepeater).
+The source code is in the [`examples/firstgenrepeater`](https://github.com/QuantumSavory/QuantumSavory.jl/tree/master/examples/firstgenrepeater) folder.
diff --git a/docs/src/howto/firstgenrepeater/firstgenrepeater.md b/docs/src/howto/firstgenrepeater/firstgenrepeater.md
@@ -1,11 +1,5 @@
 # [First Generation Quantum Repeater](@id First-Generation-Quantum-Repeater)
 
-```@meta
-DocTestSetup = quote
-    using QuantumSavory
-end
-```
-
 There is a convenient classification of quantum repeaters by their logical capabilities[^1].
 The first, simplest, generation of quantum repeaters involves the generation of physical (unencoded) entangled qubits between neighboring nodes,
 followed by entanglement swap and entanglement purification operation.
@@ -36,6 +30,9 @@ The user does not need to know much about these libraries, but if they wish, it
 
 The full simulation script is available at the bottom.
 
+!!! info "Low Level Implementation"
+    This is a very low-level implementation. You would be better of using already implemented reusable protocols like [`EntanglerProt`](https://qs.quantumsavory.org/dev/API_ProtocolZoo/#QuantumSavory.ProtocolZoo.EntanglerProt) like done in the second version of this example [`firstgenrepeater_v2`](https://qs.quantumsavory.org/dev/howto/firstgenrepeater_v2/firstgenrepeater_v2). On the other hand, the setup here is a simple way to learn about making discrete event simulations without depending on a lot of extra library functionality and opaque black boxes.
+
 ## The Underlying Data Structures
 
 While the quantum dynamics would be encapsulated in a [`Register`](@ref) data structure,
@@ -46,7 +43,7 @@ While this is not required for using `QuantumSavory.jl`, it is convenient,
 and we provide a lot of debugging tools that assume the use of this structure.
 
 Given an array of register sizes, e.g. `sizes = [2,3,4,3,2]`, we will create a linear graph,
-where each node has the prescribed number of qubits, e.g.: 
+where each node has the prescribed number of qubits, e.g.:
 
 ![An image of 5 quantum registers](./firstgenrepeater-01.graph.png)
 
@@ -563,14 +560,12 @@ Of note is that we also used
 and `QuantumOptics.jl` for convenient master equation integration.
 Many of these tools were used under the hood without being invoked directly.
 
-## Full Code
-
-The entirety of the code necessary for reproducing these results is in the
-[examples folder of the `QuantumSavory.jl` repository](https://github.com/QuantumSavory/QuantumSavory.jl/tree/master/examples/firstgenrepeater).
-
 ## Suggested Improvements
 
 - The first and most obvious improvement would be to trigger the various events (Entangler, Swapper, Purifier) from each other, instead of having them all randomly wait and hope the necessary resources are available.
 - Calibrating when to perform a purification versus a swap would be important for the performance of the network.
 - Balancing what types of entanglement purification is performed, depending on the type of noise experienced, can drastically lower resource requirements.
-- Implementing more sophisticated purification schemes can greatly improve the quality of entanglement.
+- Implementing more sophisticated purification schemes can greatly improve the quality of entanglement.
+
+
+The source code is in the [`examples/firstgenrepeater`](https://github.com/QuantumSavory/QuantumSavory.jl/tree/master/examples/firstgenrepeater) folder.
diff --git a/docs/src/howto/firstgenrepeater_v2/firstgenrepeater_v2-01.entangler.mp4 b/docs/src/howto/firstgenrepeater_v2/firstgenrepeater_v2-01.entangler.mp4
diff --git a/docs/src/howto/firstgenrepeater_v2/firstgenrepeater_v2-02.swapper.mp4 b/docs/src/howto/firstgenrepeater_v2/firstgenrepeater_v2-02.swapper.mp4
diff --git a/docs/src/howto/firstgenrepeater_v2/firstgenrepeater_v2.md b/docs/src/howto/firstgenrepeater_v2/firstgenrepeater_v2.md
@@ -0,0 +1,10 @@
+# First Generation Quantum Repeater - A Simpler Implementation
+
+!!! info "TODO Unfinished"
+    This page is unfinished!
+
+Compared to [the lower-level implementation `firstgenrepeater`](@ref First-Generation-Quantum-Repeater), which does not use convenient high-level abstractions, the code here (`firstgenrepeater_v2`) is drastically simpler. It is little more than direct calls to two pre-defined protocols available in [`QuantumSavory.ProtocolZoo`](): [`QuantumSavory.ProtocolZoo.EntanglerProt`](@ref) for probabilistic generation of nearest-neighbor entanglement and [`QuantumSavory.ProtocolZoo.SwapperProt`](@ref) for entanglement swapping, as well as [`QuantumSavory.ProtocolZoo.EntanglementTracker`](@ref) to keep track of all classical metadata and messaging necessary for the control of the network.
+
+It is instructive to compare this simple-to-use setup with the much lengthier but equivalent implementation in [`firstgenrepeater`](@ref First-Generation-Quantum-Repeater), especially if one wants to develop reusable protocols of their own.
+
+The source code is in the [`examples/firstgenrepeater_v2`](https://github.com/QuantumSavory/QuantumSavory.jl/tree/master/firstgenrepeater_v2/firstgenrepeater_v2) folder.