Merge branch 'QuantumSavory:master' into grid_docs

.github/workflows/downgrade.yml

@@ -21,9 +21,9 @@ jobs:
       - uses: julia-actions/setup-julia@v1
         with:
           version: ${{ matrix.version }}
-      - uses: cjdoris/julia-downgrade-compat-action@v1
+      - uses: julia-actions/julia-downgrade-compat@v1
         with:
-          skip: Pkg,TOML,InteractiveUtils,Random,LinearAlgebra
+          skip: Pkg,TOML,InteractiveUtils,Random,LinearAlgebra,Statistics,Printf,Combinatorics,Random,PrecompileTools
       - uses: julia-actions/cache@v1
       - uses: julia-actions/julia-buildpkg@v1
-      - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-runtest@v1

Project.toml

@@ -35,23 +35,23 @@ QuantumSavoryMakie = "Makie"
 [compat]
 Combinatorics = "1"
 ConcurrentSim = "1.4"
-Distributions = "0.25"
+Distributions = "0.25.90"
 DocStringExtensions = "0.9"
-Graphs = "1.7.3"
+Graphs = "1.9"
 IterTools = "1.4.0"
 LinearAlgebra = "1"
-Makie = "0.19, 0.20"
+Makie = "0.20"
 NetworkLayout = "0.4.4"
 PrecompileTools = "1"
 Printf = "1"
-QuantumClifford = "0.8"
-QuantumInterface = "0.3.3"
+QuantumClifford = "0.8.20"
+QuantumInterface = "0.3.4"
 QuantumOptics = "1.0.5"
-QuantumOpticsBase = "0.4.17"
+QuantumOpticsBase = "0.4.18"
 QuantumSymbolics = "0.2.5"
 Random = "1"
 Reexport = "1.2.2"
-ResumableFunctions = "0.6"
+ResumableFunctions = "0.6.9"
 Statistics = "1"
-SumTypes = "0.5.1"
+SumTypes = "0.5.5"
 julia = "1.9"

docs/make.jl

@@ -13,7 +13,7 @@ function main()
     plugins = [bib],
     doctest = false,
     clean = true,
-    warnonly = true, # TODO [:missing_docs],
+    warnonly = [:missing_docs],
     sitename = "QuantumSavory.jl",
     format = Documenter.HTML(
         assets=["assets/init.js"]
@@ -25,12 +25,11 @@ function main()
     "Getting Started Manual" => "manual.md",
     "Explanations" => [
         "explanations.md",
+        "Register Interface" => "register_interface.md",
         "Properties and Backgrounds" => "propbackgrounds.md",
         "Symbolic Expressions" => "symbolics.md",
+        "Tagging and Querying" => "tag_query.md",
         "Visualizations" => "visualizations.md",
-        "Dev Documentation" => [
-            "Register Interface" => "register_interface.md",
-        ],
     ],
     "How-To Guides" => [
         "howto.md",
@@ -49,6 +48,7 @@ function main()
         "API" => "API.md",
         "CircuitZoo API" => "API_CircuitZoo.md",
         "StatesZoo API" => "API_StatesZoo.md",
+        "ProtocolZoo API" => "API_ProtocolZoo.md",
         "Bibliography" => "bibliography.md",
     ],
     ]

docs/src/API_ProtocolZoo.md

@@ -0,0 +1,26 @@
+# Available Protocols
+
+```@raw html
+<style>
+    .content table td {
+        padding-top: 0 !important;
+        padding-bottom: 0 !important;
+    }
+</style>
+```
+
+## Autogenerated API list for `QuantumSavory.ProtocolZoo`
+
+```@autodocs
+Modules = [QuantumSavory.ProtocolZoo]
+Private = false
+```
+
+## Non-exported custom tags used by these protocols
+
+```@docs
+QuantumSavory.ProtocolZoo.EntanglementCounterpart
+QuantumSavory.ProtocolZoo.EntanglementHistory
+QuantumSavory.ProtocolZoo.EntanglementUpdateX
+QuantumSavory.ProtocolZoo.EntanglementUpdateZ
+```

docs/src/explanations.md

@@ -12,6 +12,7 @@ You probably want to cover the:
 - `Register` and `RegisterNet` structures
 - basic interface used by the library
 - symbolic capabilities for formalism-agnostic description
+- metadata tagging and metadata queries for interoperability between protocols
 - available simulator backends
 - discrete event simulations and time-tracking capabilities
 - background noise processes

docs/src/references.bib

@@ -211,7 +211,7 @@ @article{keisuke2009doubleselection
   journal={Phys. Rev. A 80, 042308},
   year={2009},
   url={https://doi.org/10.1103/PhysRevA.80.042308},
-  doi={https://doi.org/10.1103/PhysRevA.80.042308}
+  doi={10.1103/PhysRevA.80.042308}
 }
 
 @article{krastanov2019optimised,

docs/src/register_interface.md

@@ -12,6 +12,10 @@ A rather diverse set of simulation libraries is used under the hood. Long term t
 
 Initialize the state of a register to a known state.
 
+```@docs; canonical=false
+initialize!
+```
+
 #### `initialize!(refs::Vector{RegRef}, state; time)`
 
 Store a `state` in the given register slots.
@@ -66,6 +70,10 @@ flowchart TB
 
 Apply a quantum operation to a register.
 
+```@docs; canonical=false
+apply!
+```
+
 #### `apply!(refs::Vector{RegRef}, operation; time)`
 
 Applying an `operation` to the qubits referred to by the sequence of [`RegRef`](@ref)s at a specified `time`.
@@ -126,6 +134,10 @@ flowchart TB
 
 Measure a quantum observable. The dispatch down the call three is very similar to the one for `apply!`.
 
+```@docs; canonical=false
+observable
+```
+
 #### `observable(refs::Tuple{Vararg{RegRef, N}}, obs, something=nothing; time)`
 
 Calculate the value of an observable on the state in the sequence of [`RegRef`](@ref)s at a specified `time`. If these registers are not instantiated, return `something`.
@@ -180,6 +192,10 @@ flowchart TB
 
 ## `project_traceout!`
 
+```@docs; canonical=false
+project_traceout!
+```
+
 #### `project_traceout!(r::RegRef, basis; time)`
 
 Project the state in `RegRef` on `basis` at a specified `time`. `basis` can be a `Vector` or `Tuple` of basis states, or it can be a `Matrix` like `Z` or `X`.
@@ -228,6 +244,10 @@ flowchart TB
 
 ## `traceout!`
 
+```@docs; canonical=false
+traceout!
+```
+
 Perform a partial trace over a part of the system (i.e. discard a part of the system).
 
 #### `traceout!(r::RegRef)`
@@ -257,6 +277,10 @@ flowchart TB
 
 ## `uptotime!`
 
+```@docs; canonical=false
+uptotime!
+```
+
 #### `uptotime!(ref::RegRef, now)`
 
 Evolve the state in a `RegRef` upto a given time `now`

docs/src/tag_query.md

@@ -0,0 +1,75 @@
+# Tagging and Querying
+
+```@meta
+DocTestSetup =  quote
+    using QuantumSavory
+end
+```
+
+The [`query`](@ref) and [`tag!`](@ref) interface lets you manage "classical state" metadata in your simulations. In particular, this interface enables the creation of modular interoperable [control protocols](@ref "Available Protocols"). Each protocol can operate independently of others without knowledge of each others' internals. This is done by using various "tags" to communicate metadata between the network nodes running the protocols, and by the protocols querying for the presence of such tags, leading to greater flexibility when setting up different simulations.
+
+The components of the query interface which make this possible are described below.
+
+## The `Tag` type
+
+```@docs; canonical=false
+QuantumSavory.Tag
+```
+
+And here are all currently supported tag signatures:
+
+```@example
+using QuantumSavory #hide
+[tuple(m.sig.types[2:end]...) for m in methods(Tag) if m.sig.types[2] ∈ (Symbol, DataType)]
+```
+
+## Assigning and removing tags
+
+```@docs; canonical=false
+QuantumSavory.tag!
+QuantumSavory.untag!
+```
+
+## Querying for the pressence of a tag
+
+The [`query`](@ref) function allows the user to query for [`Tag`](@ref)s in three different cases:
+- on a particular qubit slot ([`RegRef`](@ref)) in a [`Register`](@ref) node;
+- on a [`Register`](@ref) to query for any slot that contains the passed `Tag`;
+- on a [`messagebuffer`](@ref) to query for a particular `Tag` received from another node in a network.
+
+The `Tag` description passed to `query` can include predicate functions (of the form `x -> pass::Bool`) and wildcards (the [`❓`](@ref) variable), for situations where we have freedom in what tag we are exactly searching for.
+
+The queries can search in `FIFO` or `FILO` order (`FILO` by default). E.g., for the default `FILO`, a query on a [`RegRef`](@ref) returns the `Tag` which is at the end of the vector of tags stored the given slot (as new tags are appended at the end). On a [`Register`](@ref) it returns the slot with the "youngest" age.
+
+One can also query by "lock" and "assignment" status of a given slot, by using the `locked` and `assigned` boolean keywords. By default these keywords are set to `nothing` and these properties are not checked.
+
+Following is a detailed description of each `query` methods
+
+```@docs; canonical=false
+query(::Register,::Tag)
+query(::RegRef,::Tag) 
+query(::MessageBuffer,::Tag)
+```
+
+### Wildcards
+
+```@docs; canonical=false
+W
+❓
+```
+
+### `querydelete!`
+
+A method on top of [`query`](@ref), which allows to query for tag in a [`RegRef`](@ref) or a [`messagebuffer`](@ref), returning the tag that satisfies the passed predicates and wildcars, **and deleting it from the list at the same time**. It otherwise has the same signature as [`query`](@ref).
+
+```@docs; canonical=false
+querydelete!(::RegRef)
+querydelete!(::MessageBuffer)
+```
+
+### `queryall`
+A method defined on top of [`query`](@ref) which allows to query for **all tags** in a [`RegRef`](@ref) or a [`Register`](@ref) that match the query.
+
+```@docs; canonical=false
+QuantumSavory.queryall
+```

docs/src/tutorial/message_queues.md

@@ -132,22 +132,22 @@ time_before_success = now(sim)
 
 ## Communication delay
 
-Classical communication delay might be important too. There are FILO storage stacks that can simulate that, e.g. `DelayChannel(sim, delay_time)` used instead of `Storage(sim)`. Below we augment the example from above with such a delay channel and we also add some crude instrumentation and plotting.
+Classical communication delay might be important too. There are FILO storage stacks that can simulate that, e.g. `DelayQueue(sim, delay_time)` used instead of `Storage(sim)`. Below we augment the example from above with such a delay channel and we also add some crude instrumentation and plotting.
 
 ```@example messagechannel
 sim = Simulation()
 communication_delay = 1.0
-channel_1to2 = DelayChannel{Bool}(sim, communication_delay)
-channel_2to1 = DelayChannel{Bool}(sim, communication_delay)
-channel_ready = DelayChannel{Bool}(sim, communication_delay)
+channel_1to2 = DelayQueue{Bool}(sim, communication_delay)
+channel_2to1 = DelayQueue{Bool}(sim, communication_delay)
+channel_ready = DelayQueue{Bool}(sim, communication_delay)
 
 global_log = []
 
 @resumable function do_random_measurement_transmit_receive_compare(sim, channel_out, channel_in)
     @yield timeout(sim, 2+rand())   # wait for the measurement to take place
     local_measurement = rand() < 0.4 # simulate a random measurement result
-    put(channel_out, local_measurement)
-    other_measurement = @yield get(channel_in)
+    put!(channel_out, local_measurement)
+    other_measurement = @yield take!(channel_in)
     succeeded = local_measurement == other_measurement == true
     return succeeded
 end
@@ -156,7 +156,7 @@ end
     s = now(sim)
     reset_duration = 2.0
     @yield timeout(sim, reset_duration)
-    put(channel_ready, true)
+    put!(channel_ready, true)
     push!(global_log, (:reset_system, s, now(sim)))
 end
 
@@ -183,7 +183,7 @@ end
         end
         push!(global_log, (:node_2_meas_tx_rx, s, now(sim)))
         s2 = now(sim)
-        @yield get(channel_ready)
+        @yield take!(channel_ready)
         push!(global_log, (:node_2_wait_for_reset, s2, now(sim)))
     end
 end