significant improvements and cleanup to registernetplot

docs/src/tutorial/message_queues.md

@@ -7,6 +7,14 @@ DocTestSetup = quote
 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)
+    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.
+
 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/visualizations.md

@@ -21,13 +21,7 @@ using CairoMakie # or GLMakie for interactive plots
 using QuantumSavory
 
 # create a network of qubit registers
-sizes = [2,3,2,5]
-registers = Register[]
-for s in sizes
-    traits = [Qubit() for _ in 1:s]
-    push!(registers, Register(traits))
-end
-network = RegisterNet(registers)
+network = RegisterNet([Register(2),Register(3),Register(2),Register(5)])
 
 # add some states, entangle a few slots, perform some gates
 initialize!(network[1,1])
@@ -41,6 +35,16 @@ _, _, plt, obs = registernetplot_axis(fig[1,1],network)
 fig
 ```
 
+The tall rectangles are registers, the gray squares are the slots of these registers, and the (connected) black diamonds denote when a slot is occupied by some subsystem (of a potentially larger) quantum state.
+
+The visualization is capable of showing tooltips when hovering over different components of the plot, particularly valuable for debugging. Quantum observables can be directly calculated and plotted as well (through the `observables` keyword).
+
+Other configuration options are available as well (the ones ending on `plot` let you access the subplot objects used to create the visualization and the ones ending on `backref` provide convenient inverse mapping from graphical elements to the registers or states being visualized):
+
+```@example vis
+propertynames(plt)
+```
+
 ## 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.

src/QuantumSavory.jl

@@ -56,7 +56,7 @@ export
     # noninstant.jl
     AbstractNoninstantOperation, NonInstantGate, ConstantHamiltonianEvolution,
     # plots.jl
-    registernetplot, registernetplot_axis, resourceplot_axis
+    registernetplot, registernetplot!, registernetplot_axis, resourceplot_axis
 
 
 #TODO you can not assume you can always in-place modify a state. Have all these functions work on stateref, not stateref[]

src/plots.jl

@@ -1,9 +1,14 @@
-"""Draw the given registers on a given Makie axis.
+"""Draw the given register network.
 
 Requires a Makie backend be already imported."""
 function registernetplot end
 
-"""Draw the given registers on a given Makie axis.
+"""Draw the given register network on a given Makie axis.
+
+Requires a Makie backend be already imported."""
+function registernetplot! end
+
+"""Draw the given register network on a given Makie subfigure and modify the axis with numerous visualization enhancements.
 
 Requires a Makie backend be already imported."""
 function registernetplot_axis end

test/test_plotting_2_tags_observables.jl

@@ -0,0 +1,97 @@
+using QuantumSavory
+#using CairoMakie
+#using GLMakie
+using Graphs
+using FileIO
+
+##
+
+regnet = RegisterNet([Register(2), Register(3)])
+fig = Figure()
+ax = Makie.Axis(fig[1, 1])
+p = registernetplot!(ax, regnet)
+ax.aspect = Makie.DataAspect()
+Makie.hidedecorations!(ax)
+Makie.hidespines!(ax)
+fig
+
+##
+
+regnet = RegisterNet([Register(2), Register(3)])
+
+##
+
+fig = Figure()
+ax = Axis(fig[1,1])
+@test_throws ArgumentError registernetplot!(ax, RegisterNet([Register(2)]), registercoords=rand(2,1))
+@test_throws ArgumentError registernetplot!(ax, RegisterNet([Register(2)]), registercoords=rand(1,2))
+@test_throws ArgumentError registernetplot!(ax, RegisterNet([Register(2)]), registercoords=[1.1,1.1])
+@test_throws ArgumentError registernetplot!(ax, RegisterNet([Register(2)]), registercoords=[[1.1,1.1]])
+@test_throws ArgumentError registernetplot!(ax, RegisterNet([Register(2)]), registercoords=[(1.1,1.1)])
+registernetplot!(ax, RegisterNet([Register(2)]), registercoords=[Point2f(1,1)])
+display(fig)
+
+##
+
+fig = Figure()
+ax = Axis(fig[1,1])
+@test_throws ArgumentError registernetplot!(ax, RegisterNet([Register(2)]), observables=[("pretend I am an operator",)])
+@test_throws ArgumentError registernetplot!(ax, RegisterNet([Register(2)]), observables=[(X, 1)])
+@test_throws ArgumentError registernetplot!(ax, RegisterNet([Register(2)]), observables=[(X, (1,1))])
+registernetplot!(ax, RegisterNet([Register(2)]), observables=[(X, ((1,1),))])
+net = RegisterNet([Register(2)])
+initialize!(net[1,1], X1)
+registernetplot!(ax, net, observables=[(X, ((1,1),), [(1,1),(1,1)])])
+@test_throws ArgumentError registernetplot!(ax, RegisterNet([Register(2)]), observables=[(X, ((1,1),), ((1,1),))]) # TODO consider permitting this
+display(fig)
+
+##
+
+fig = Figure()
+ax = Axis(fig[1,1])
+net = RegisterNet([Register(2),Register(2),Register(2), Register(1)])
+initialize!((net[1,1], net[2,2], net[3,2]), X1⊗X1⊗X1)
+initialize!((net[1,2], net[3,1]), X1⊗X1)
+initialize!(net[2,1], X1)
+p = registernetplot!(ax, net, observables=[(X, ((1,2),)), (X⊗X⊗X, ((1,1),(2,2),(3,2)))])
+display(fig)
+
+##
+
+fig = Figure()
+registernetplot_axis(fig[1,1], RegisterNet([Register(1), Register(2)]),
+                  slotcolor=:red)
+display(fig)
+
+##
+
+fig = Figure()
+registernetplot_axis(fig[1,1], RegisterNet([Register(1), Register(2)]),
+                  slotcolor=(:red,0.1))
+display(fig)
+
+##
+
+fig = Figure()
+registernetplot_axis(fig[1,1], RegisterNet([Register(1), Register(2)]),
+                  slotcolor=[(:red,0.1), :blue, :gray10])
+display(fig)
+
+##
+
+fig = Figure()
+registernetplot_axis(fig[1,1], RegisterNet([Register(1), Register(2)]),
+                  slotcolor=[[(:red,0.1)], [:blue, :gray10]])
+display(fig)
+
+##
+
+fig = Figure()
+net = RegisterNet([Register(2),Register(2),Register(2), Register(1)])
+initialize!((net[1,1], net[2,2], net[3,2]), X1⊗X1⊗X1)
+initialize!((net[1,2], net[3,1]), X1⊗X1)
+tag!(net[4,1], Tag(:mytag, 1, 2))
+tag!(net[3,1], Tag(:sometag, 10, 20))
+initialize!(net[2,1], X1)
+p = registernetplot_axis(fig[1,1], net, observables=[(X, ((1,2),)), (X⊗X⊗X, ((1,1),(2,2),(3,2)))], infocli=false)
+display(fig)

test/test_plotting_cairo.jl

@@ -1,3 +1,10 @@
+using Test
 using CairoMakie
 CairoMakie.activate!()
-include("test_plotting.jl")
+
+@testset "register coordinates" begin
+    include("test_plotting_1_regcoords.jl")
+end
+@testset "arguments and observables and tags" begin
+    include("test_plotting_2_tags_observables.jl")
+end

test/test_plotting_gl.jl

@@ -1,3 +1,10 @@
+using Test
 using GLMakie
 GLMakie.activate!()
-include("test_plotting.jl")
+
+@testset "register coordinates" begin
+    include("test_plotting_1_regcoords.jl")
+end
+@testset "arguments and observables and tags" begin
+    include("test_plotting_2_tags_observables.jl")
+end