documentation for the data inspection feature in plotting

.github/workflows/ci.yml

@@ -43,12 +43,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Install binary dependencies
+        run: sudo apt-get update && sudo apt-get install -y xorg-dev mesa-utils xvfb libgl1 freeglut3-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxext-dev
       - uses: julia-actions/setup-julia@v1
         with:
           version: '1'
       - uses: julia-actions/cache@v1
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-docdeploy@v1
+        with:
+          prefix: xvfb-run
         env:
           GKSwstype: nul # Fix for Plots with GR backend.
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/Project.toml

@@ -4,6 +4,7 @@ ConcurrentSim = "6ed1e86c-fcaf-46a9-97e0-2b26a2cdb499"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
 GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"

docs/make.jl

@@ -40,7 +40,7 @@ function main()
     "Tutorials" => [
         "tutorial.md",
         "Gate duration" => "tutorial/noninstantgate.md",
-        "Message queues" => "tutorial/message_queues.md",
+        #"Message queues" => "tutorial/message_queues.md", TODO
         #"Depolarization and Pauli Noise" => "tutorial/depolarization_and_pauli.md", TODO
     ],
     "References" => [

docs/src/tutorial/message_queues.md → docs/outdated/message_queues.md

@@ -10,10 +10,10 @@ end
 !!! warning
 
     This section is rather low-level, created before a lot of user-friendly tools were added.
-    The approach described here still functions well, however we now provide a more convenient interface and pre-build message passing channels.
-    In particular, the tagging & querying system (based on `tag!` and `query`), the [`messagebuffer`](@ref), and the available [`channel`](@ref), [`qchannel`](@ref) and [`QuantumChannel`](@ref)
+    The approach described here functions well, however we now provide a more convenient interface and pre-build message passing channels.
+    In particular, the tagging & querying system (based on [`tag!`](@ref) and [`query`](@ref)), the [`messagebuffer`](@ref), and the available [`channel`](@ref), [`qchannel`](@ref) and [`QuantumChannel`](@ref)
     probably cover all your needs.
-    You might still be interested in reading this section in order to learn some of the low-level tooling on which the more recent developments were built.
+    You might still be interested in reading this section in order to learn some of the low-level tooling on which the higher-level interfaces were built.
 
 In network simulations, a convenient synchronization primitive is the passing of messages between nodes.
 The `ResumableFunctions` and `ConcurrentSim` libraries provide such primitives, convenient to use with `QuatumSavory`.

docs/src/tag_query.md

@@ -1,4 +1,4 @@
-# Tagging and Querying
+# [Tagging and Querying](@id tagging-and-querying)
 
 ```@meta
 DocTestSetup =  quote

docs/src/visualizations.md

@@ -17,21 +17,21 @@ This is particularly useful for live simulation visualizations.
 The [`registernetplot_axis`](@ref) function can be used to draw a given set of registers, together with the quantum states they contain. It also provides interactive tools for inspecting the content of the registers (by hovering or clicking on the corresponding register slot). Here we give an example where we define a network and then plot it:
 
 ```@example vis
-using CairoMakie # or GLMakie for interactive plots
+using GLMakie
 using QuantumSavory
 
 # create a network of qubit registers
-network = RegisterNet([Register(2),Register(3),Register(2),Register(5)])
+net = RegisterNet([Register(2),Register(3),Register(2),Register(5)])
 
 # add some states, entangle a few slots, perform some gates
-initialize!(network[1,1])
-initialize!(network[2,3], X₁)
-initialize!((network[3,1],network[4,2]), X₁⊗Z₂)
-apply!((network[2,3],network[3,1]), CNOT)
+initialize!(net[1,1])
+initialize!(net[2,3], X₁)
+initialize!((net[3,1],net[4,2]), X₁⊗Z₂)
+apply!((net[2,3],net[3,1]), CNOT)
 
 # create the plot
-fig = Figure(resolution=(400,400))
-_, _, plt, obs = registernetplot_axis(fig[1,1],network)
+fig = Figure(resolution=(800,400))
+_, ax, plt, obs = registernetplot_axis(fig[1,1],net)
 fig
 ```
 
@@ -45,6 +45,33 @@ Other configuration options are available as well (the ones ending on `plot` let
 propertynames(plt)
 ```
 
+## State and tag metadata in interactive visualizations
+
+When working with interactive plots, you can also hover over different parts of the visualization to see the registers, what is stored in them, and potentially whether they contain any [tagged metadata in use by simulated networking protocols](@ref tagging-and-querying).
+
+Here is what the data panels look like. (`showmetada` is used to force-show the panel, but when working interactively you simply need to hover with the cursor)
+
+```@example vis
+network = RegisterNet([Register(2),Register(3),Register(2),Register(5)]) # hide
+initialize!(network[1,1]) # hide
+initialize!(network[2,3], X₁) # hide
+initialize!((network[3,1],network[4,2]), X₁⊗Z₂) # hide
+apply!((network[2,3],network[3,1]), CNOT) # hide
+fig = Figure(resolution=(400,400)) # hide
+_, _, plt, obs = registernetplot_axis(fig[1,1],network) # hide
+QuantumSavory.showmetadata(fig,ax,plt,1,1)
+fig
+```
+
+And here with some extra tag metadata.
+
+```@example vis
+tag!(net[2,3], :specialplace, 1, 2)
+tag!(net[2,3], :otherdata, 3, 4)
+QuantumSavory.showmetadata(fig,ax,plt,2,3)
+fig
+```
+
 ## The state of locks and various metadata in the network
 
 The [`resourceplot_axis`](@ref) function can be used to draw all locks and resources stored in a meta-graph governing a discrete event simulation. Metadata stored at the vertices is plotted as colored or grayed out dots depending on their state. Metadata stored at the edges is shown as lines.
@@ -56,20 +83,20 @@ using ConcurrentSim
 sim = Simulation()
 
 # add random metadata to vertices and edges of the network
-for v in vertices(network)
-    network[v,:bool] = rand(Bool)
-    network[v,:resource] = Resource(sim,1)
-    rand(Bool) && request(network[v,:resource])
+for v in vertices(net)
+    net[v,:bool] = rand(Bool)
+    net[v,:resource] = Resource(sim,1)
+    rand(Bool) && request(net[v,:resource])
 end
-for e in edges(network)
-    network[e,:edge_bool] = true
-    network[e,:another_bool] = rand(Bool)
+for e in edges(net)
+    net[e,:edge_bool] = true
+    net[e,:another_bool] = rand(Bool)
 end
 
 # plot the resources and metadata
 
 fig = Figure(resolution=(700,400))
-resourceplot_axis(fig[1,1],network,
+resourceplot_axis(fig[1,1],net,
     [:edge_bool,:another_bool], # list of edge metadata to plot
     [:bool,:resource],          # list of vertex metadata
     registercoords=plt[:registercoords] # optionally, reuse register coordinates

ext/QuantumSavoryMakie/QuantumSavoryMakie.jl

@@ -10,7 +10,7 @@
     Point2, Point2f, Rect2f,
     scatter!, poly!, linesegments!,
     DataInspector
-import QuantumSavory: registernetplot, registernetplot!, registernetplot_axis, resourceplot_axis, showonplot
+import QuantumSavory: registernetplot, registernetplot!, registernetplot_axis, resourceplot_axis, showonplot, showmetadata
 
 ##
 
@@ -351,4 +351,11 @@
     subfig, axis, baseplot, networkobs
 end
 
+##
+
+function showmetadata(fig, ax, p, reg, slot)
+    Makie.events(fig).mouseposition[] =
+    tuple(Makie.shift_project(ax.scene, p.registercoords[][reg].+(0,slot-1))...);
+end
+
 end

src/plots.jl

@@ -18,4 +18,7 @@ function registernetplot_axis end
 Requires a Makie backend be already imported."""
 function resourceplot_axis end
 
+"""Show the metadata tooltip for a given register slot."""
+function showmetadata end
+
 function showonplot end