Refactoring ZX implementation

.gitignore

@@ -9,3 +9,4 @@
 /docs/Manifest.toml
 .vscode
 .JuliaFormatter.toml
+lcov.info

Project.toml

@@ -1,11 +1,13 @@
 name = "ZXCalculus"
 uuid = "3525faa3-032d-4235-a8d4-8c2939a218dd"
-authors = ["Chen Zhao and contributors"]
 version = "0.7.1"
+authors = ["Chen Zhao and contributors"]
 
 [deps]
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 Expronicon = "6b7a57c9-7cc1-4fdf-b7f5-e857abae3636"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MLStyle = "d8e11817-5142-5d16-987a-aa16d5891078"
 Multigraphs = "7ebac608-6c66-46e6-9856-b5f43e107bac"
@@ -23,8 +25,10 @@ ZXCalculusExt = ["Vega", "DataFrames"]
 
 [compat]
 DataFrames = "1"
+DocStringExtensions = "0.9.5"
 Expronicon = "0.10.3"
 Graphs = "1"
+JSON = "0.21.4"
 MLStyle = "0.4"
 Multigraphs = "0.3"
 OMEinsum = "0.7, 0.8, 0.9"

docs/src/examples.md

@@ -10,33 +10,33 @@ This example can be found in the appendix of [Clifford simplification](https://a
 using ZXCalculus
 
 function generate_example_1()
-    zxd = ZXDiagram(4)
-    push_gate!(zxd, Val(:Z), 1, 3//2)
-    push_gate!(zxd, Val(:H), 1)
-    push_gate!(zxd, Val(:Z), 1, 1//2)
-    push_gate!(zxd, Val(:H), 4)
-    push_gate!(zxd, Val(:CZ), 4, 1)
-    push_gate!(zxd, Val(:CNOT), 1, 4)
-    push_gate!(zxd, Val(:H), 1)
-    push_gate!(zxd, Val(:H), 4)
-    push_gate!(zxd, Val(:Z), 1, 1//4)
-    push_gate!(zxd, Val(:Z), 4, 3//2)
-    push_gate!(zxd, Val(:X), 4, 1//1)
-    push_gate!(zxd, Val(:H), 1)
-    push_gate!(zxd, Val(:Z), 4, 1//2)
-    push_gate!(zxd, Val(:X), 4, 1//1)
-    push_gate!(zxd, Val(:Z), 2, 1//2)
-    push_gate!(zxd, Val(:CNOT), 3, 2)
-    push_gate!(zxd, Val(:H), 2)
-    push_gate!(zxd, Val(:CNOT), 3, 2)
-    push_gate!(zxd, Val(:Z), 2, 1//4)
-    push_gate!(zxd, Val(:Z), 3, 1//2)
-    push_gate!(zxd, Val(:H), 2)
-    push_gate!(zxd, Val(:H), 3)
-    push_gate!(zxd, Val(:Z), 3, 1//2)
-    push_gate!(zxd, Val(:CNOT), 3, 2)
-
-    return zxd
+    zxc = ZXCircuit(4)
+    push_gate!(zxc, Val(:Z), 1, 3//2)
+    push_gate!(zxc, Val(:H), 1)
+    push_gate!(zxc, Val(:Z), 1, 1//2)
+    push_gate!(zxc, Val(:H), 4)
+    push_gate!(zxc, Val(:CZ), 4, 1)
+    push_gate!(zxc, Val(:CNOT), 1, 4)
+    push_gate!(zxc, Val(:H), 1)
+    push_gate!(zxc, Val(:H), 4)
+    push_gate!(zxc, Val(:Z), 1, 1//4)
+    push_gate!(zxc, Val(:Z), 4, 3//2)
+    push_gate!(zxc, Val(:X), 4, 1//1)
+    push_gate!(zxc, Val(:H), 1)
+    push_gate!(zxc, Val(:Z), 4, 1//2)
+    push_gate!(zxc, Val(:X), 4, 1//1)
+    push_gate!(zxc, Val(:Z), 2, 1//2)
+    push_gate!(zxc, Val(:CNOT), 3, 2)
+    push_gate!(zxc, Val(:H), 2)
+    push_gate!(zxc, Val(:CNOT), 3, 2)
+    push_gate!(zxc, Val(:Z), 2, 1//4)
+    push_gate!(zxc, Val(:Z), 3, 1//2)
+    push_gate!(zxc, Val(:H), 2)
+    push_gate!(zxc, Val(:H), 3)
+    push_gate!(zxc, Val(:Z), 3, 1//2)
+    push_gate!(zxc, Val(:CNOT), 3, 2)
+
+    return zxc
 end
 ex1 = generate_example_1()
 ```
@@ -46,17 +46,16 @@ using YaoPlots
 plot(ex1)
 ```
 ![the circuit of example 1](imgs/ex1.svg)
-To simplify `zxd`, one can simply use
+To simplify `ex1`, one can simply use
 ```julia
 simplified_ex1 = clifford_simplification(ex1)
 ```
-or explicitly use
+or explicitly apply the simplification rules:
 ```julia
-zxg = ZXGraph(ex1)
-simplify!(Rule{:lc}(), zxg)
-simplify!(Rule{:p1}(), zxg)
-replace!(Rule{:pab}(), zxg)
-simplified_ex1 = circuit_extraction(zxg)
+simplify!(LocalCompRule(), ex1)
+simplify!(Pivot1Rule(), ex1)
+replace!(PivotBoundaryRule(), ex1)
+simplified_ex1 = circuit_extraction(ex1)
 ```
 And we draw the simplified circuit.
 ```julia
@@ -72,77 +71,77 @@ We first build up the circuit.
 ```julia
 using ZXCalculus, YaoPlots
 function generate_example2()
-    cir = ZXDiagram(5)
-    push_gate!(cir, Val(:X), 5, 1//1)
-    push_gate!(cir, Val(:H), 5)
-    push_gate!(cir, Val(:Z), 5)
-    push_gate!(cir, Val(:CNOT), 5, 4)
-    push_gate!(cir, Val(:Z), 5, 7//4)
-    push_gate!(cir, Val(:CNOT), 5, 1)
-    push_gate!(cir, Val(:Z), 5, 1//4)
-    push_gate!(cir, Val(:CNOT), 5, 4)
-    push_gate!(cir, Val(:Z), 4, 1//4)
-    push_gate!(cir, Val(:Z), 5, 7//4)
-    push_gate!(cir, Val(:CNOT), 5, 1)
-    push_gate!(cir, Val(:CNOT), 4, 1)
-    push_gate!(cir, Val(:Z), 5, 1//4)
-    push_gate!(cir, Val(:Z), 1, 1//4)
-    push_gate!(cir, Val(:Z), 4, 7//4)
-    push_gate!(cir, Val(:CNOT), 4, 1)
-    push_gate!(cir, Val(:CNOT), 5, 4)
-    push_gate!(cir, Val(:Z), 5, 7//4)
-    push_gate!(cir, Val(:CNOT), 5, 3)
-    push_gate!(cir, Val(:Z), 5, 1//4)
-    push_gate!(cir, Val(:CNOT), 5, 4)
-    push_gate!(cir, Val(:Z), 4, 1//4)
-    push_gate!(cir, Val(:Z), 5, 7//4)
-    push_gate!(cir, Val(:CNOT), 5, 3)
-    push_gate!(cir, Val(:CNOT), 4, 3)
-    push_gate!(cir, Val(:Z), 5, 1//4)
-    push_gate!(cir, Val(:Z), 3, 1//4)
-    push_gate!(cir, Val(:Z), 4, 7//4)
-    push_gate!(cir, Val(:H), 5)
-    push_gate!(cir, Val(:Z), 5)
-    push_gate!(cir, Val(:CNOT), 4, 3)
-    push_gate!(cir, Val(:CNOT), 5, 4)
-    push_gate!(cir, Val(:H), 5)
-    push_gate!(cir, Val(:Z), 5)
-    push_gate!(cir, Val(:CNOT), 5, 3)
-    push_gate!(cir, Val(:Z), 5, 7//4)
-    push_gate!(cir, Val(:CNOT), 5, 2)
-    push_gate!(cir, Val(:Z), 5, 1//4)
-    push_gate!(cir, Val(:CNOT), 5, 3)
-    push_gate!(cir, Val(:Z), 3, 1//4)
-    push_gate!(cir, Val(:Z), 5, 7//4)
-    push_gate!(cir, Val(:CNOT), 5, 2)
-    push_gate!(cir, Val(:CNOT), 3, 2)
-    push_gate!(cir, Val(:Z), 5, 1//4)
-    push_gate!(cir, Val(:H), 5)
-    push_gate!(cir, Val(:Z), 2, 1//4)
-    push_gate!(cir, Val(:Z), 3, 7//4)
-    push_gate!(cir, Val(:Z), 5)
-    push_gate!(cir, Val(:CNOT), 3, 2)
-    push_gate!(cir, Val(:CNOT), 5, 3)
-    push_gate!(cir, Val(:H), 5)
-    push_gate!(cir, Val(:Z), 5)
-    push_gate!(cir, Val(:CNOT), 5, 2)
-    push_gate!(cir, Val(:Z), 5, 7//4)
-    push_gate!(cir, Val(:CNOT), 5, 1)
-    push_gate!(cir, Val(:Z), 5, 1//4)
-    push_gate!(cir, Val(:CNOT), 5, 2)
-    push_gate!(cir, Val(:Z), 2, 1//4)
-    push_gate!(cir, Val(:Z), 5, 7//4)
-    push_gate!(cir, Val(:CNOT), 5, 1)
-    push_gate!(cir, Val(:CNOT), 2, 1)
-    push_gate!(cir, Val(:Z), 5, 1//4)
-    push_gate!(cir, Val(:Z), 1, 1//4)
-    push_gate!(cir, Val(:Z), 2, 7//4)
-    push_gate!(cir, Val(:H), 5)
-    push_gate!(cir, Val(:Z), 5)
-    push_gate!(cir, Val(:CNOT), 2, 1)
-    push_gate!(cir, Val(:CNOT), 5, 2)
-    push_gate!(cir, Val(:CNOT), 5, 1)
-    return cir
+    zxc = ZXCircuit(5)
+    push_gate!(zxc, Val(:X), 5, 1//1)
+    push_gate!(zxc, Val(:H), 5)
+    push_gate!(zxc, Val(:Z), 5)
+    push_gate!(zxc, Val(:CNOT), 5, 4)
+    push_gate!(zxc, Val(:Z), 5, 7//4)
+    push_gate!(zxc, Val(:CNOT), 5, 1)
+    push_gate!(zxc, Val(:Z), 5, 1//4)
+    push_gate!(zxc, Val(:CNOT), 5, 4)
+    push_gate!(zxc, Val(:Z), 4, 1//4)
+    push_gate!(zxc, Val(:Z), 5, 7//4)
+    push_gate!(zxc, Val(:CNOT), 5, 1)
+    push_gate!(zxc, Val(:CNOT), 4, 1)
+    push_gate!(zxc, Val(:Z), 5, 1//4)
+    push_gate!(zxc, Val(:Z), 1, 1//4)
+    push_gate!(zxc, Val(:Z), 4, 7//4)
+    push_gate!(zxc, Val(:CNOT), 4, 1)
+    push_gate!(zxc, Val(:CNOT), 5, 4)
+    push_gate!(zxc, Val(:Z), 5, 7//4)
+    push_gate!(zxc, Val(:CNOT), 5, 3)
+    push_gate!(zxc, Val(:Z), 5, 1//4)
+    push_gate!(zxc, Val(:CNOT), 5, 4)
+    push_gate!(zxc, Val(:Z), 4, 1//4)
+    push_gate!(zxc, Val(:Z), 5, 7//4)
+    push_gate!(zxc, Val(:CNOT), 5, 3)
+    push_gate!(zxc, Val(:CNOT), 4, 3)
+    push_gate!(zxc, Val(:Z), 5, 1//4)
+    push_gate!(zxc, Val(:Z), 3, 1//4)
+    push_gate!(zxc, Val(:Z), 4, 7//4)
+    push_gate!(zxc, Val(:H), 5)
+    push_gate!(zxc, Val(:Z), 5)
+    push_gate!(zxc, Val(:CNOT), 4, 3)
+    push_gate!(zxc, Val(:CNOT), 5, 4)
+    push_gate!(zxc, Val(:H), 5)
+    push_gate!(zxc, Val(:Z), 5)
+    push_gate!(zxc, Val(:CNOT), 5, 3)
+    push_gate!(zxc, Val(:Z), 5, 7//4)
+    push_gate!(zxc, Val(:CNOT), 5, 2)
+    push_gate!(zxc, Val(:Z), 5, 1//4)
+    push_gate!(zxc, Val(:CNOT), 5, 3)
+    push_gate!(zxc, Val(:Z), 3, 1//4)
+    push_gate!(zxc, Val(:Z), 5, 7//4)
+    push_gate!(zxc, Val(:CNOT), 5, 2)
+    push_gate!(zxc, Val(:CNOT), 3, 2)
+    push_gate!(zxc, Val(:Z), 5, 1//4)
+    push_gate!(zxc, Val(:H), 5)
+    push_gate!(zxc, Val(:Z), 2, 1//4)
+    push_gate!(zxc, Val(:Z), 3, 7//4)
+    push_gate!(zxc, Val(:Z), 5)
+    push_gate!(zxc, Val(:CNOT), 3, 2)
+    push_gate!(zxc, Val(:CNOT), 5, 3)
+    push_gate!(zxc, Val(:H), 5)
+    push_gate!(zxc, Val(:Z), 5)
+    push_gate!(zxc, Val(:CNOT), 5, 2)
+    push_gate!(zxc, Val(:Z), 5, 7//4)
+    push_gate!(zxc, Val(:CNOT), 5, 1)
+    push_gate!(zxc, Val(:Z), 5, 1//4)
+    push_gate!(zxc, Val(:CNOT), 5, 2)
+    push_gate!(zxc, Val(:Z), 2, 1//4)
+    push_gate!(zxc, Val(:Z), 5, 7//4)
+    push_gate!(zxc, Val(:CNOT), 5, 1)
+    push_gate!(zxc, Val(:CNOT), 2, 1)
+    push_gate!(zxc, Val(:Z), 5, 1//4)
+    push_gate!(zxc, Val(:Z), 1, 1//4)
+    push_gate!(zxc, Val(:Z), 2, 7//4)
+    push_gate!(zxc, Val(:H), 5)
+    push_gate!(zxc, Val(:Z), 5)
+    push_gate!(zxc, Val(:CNOT), 2, 1)
+    push_gate!(zxc, Val(:CNOT), 5, 2)
+    push_gate!(zxc, Val(:CNOT), 5, 1)
+    return zxc
 end
 ex2 = generate_example2()
 plot(ex2)
@@ -166,25 +165,30 @@ we can see that the number of T gates has decreased from 28 to 8.
 
 ## Other usages
 
-In the previous sections, we introduced how to use `ZXCalculus.jl` for ZX-diagrams which represent quantum circuits. Sometimes, one may wish to use it for general ZX-diagrams. It is possible.
+In the previous sections, we introduced how to use `ZXCalculus.jl` for quantum circuits using `ZXCircuit`. Sometimes, one may wish to work with the lower-level graph representation directly.
+
+### Working with ZXGraph directly
+
+For advanced users who need direct access to the graph structure, you can work with `ZXGraph`. However, for most use cases, `ZXCircuit` is the recommended interface.
 
-One can create a `ZXDiagram` by building up its `Multigraph` and other information. For example,
 ```julia
 using ZXCalculus, YaoPlots, Graphs
-g = Multigraph(6)
-add_edge!(g, 1, 2)
-add_edge!(g, 2, 3)
-add_edge!(g, 3, 4)
-add_edge!(g, 3, 5)
-add_edge!(g, 3, 6)
-ps = [0, 1, 1//2, 0, 0, 0]
-v_t = [SpiderType.In, SpiderType.X, SpiderType.Z, SpiderType.Out, SpiderType.Out, SpiderType.Out]
-zxd = ZXDiagram(g, v_t, ps)
+
+# Create a ZXCircuit first
+zxc = ZXCircuit(3)
+push_gate!(zxc, Val(:H), 1)
+push_gate!(zxc, Val(:CNOT), 1, 2)
+
+# Access the underlying ZXGraph if needed for low-level operations
+zxg = zxc.zxd  # The internal ZXGraph
+
+# Apply graph-based rules
+simplify!(LocalCompRule(), zxc)
 ```
-Because the information of vertices locations of a general ZX-diagram is not provided, its plot will have a random layout.
 
-We can manipulate `zxd` by using ZX-calculus [`Rule`](@ref)s.
+### Deprecated: ZXDiagram
+
+**Note:** `ZXDiagram` is deprecated. For circuit-based operations, use `ZXCircuit` instead. If you have existing code using `ZXDiagram`, you can convert it:
 ```julia
-matches = match(Rule{:pi}(), zxd)
-rewrite!(Rule{:pi}(), zxd, matches)
+zxc = ZXCircuit(old_zxd)  # Convert deprecated ZXDiagram to ZXCircuit
 ```