Merge branch 'master' of https://github.com/Happy-Diode/GraphTensorNetworks.jl

Author: GiggleLiu

Project.toml

@@ -28,7 +28,7 @@ TropicalNumbers = "b3a74e9c-7526-4576-a4eb-79c0d4c32334"
 Viznet = "52a3aca4-6234-47fd-b74a-806bdf78ede9"
 
 [compat]
-AbstractTrees = "0.3"
+AbstractTrees = "0.3, 0.4"
 CUDA = "3.5"
 Cairo = "1.0"
 Compose = "0.9"

docs/make.jl

@@ -10,7 +10,7 @@ for each in readdir(pkgdir(GenericTensorNetworks, "examples"))
     input_file = pkgdir(GenericTensorNetworks, "examples", each)
     endswith(input_file, ".jl") || continue
     @info "building" input_file
-    output_dir = pkgdir(GenericTensorNetworks, "docs", "src", "tutorials")
+    output_dir = pkgdir(GenericTensorNetworks, "docs", "src", "generated")
     @info "executing" input_file
     Literate.markdown(input_file, output_dir; name=each[1:end-3], execute=false)
 end
@@ -47,24 +47,24 @@ makedocs(;
     pages=[
         "Home" => "index.md",
         "Problems" => [
-            "Independent set problem" => "tutorials/IndependentSet.md",
-            "Maximal independent set problem" => "tutorials/MaximalIS.md",
-            "Cutting problem" => "tutorials/MaxCut.md",
-            "Vertex Matching problem" => "tutorials/Matching.md",
-            "Binary paint shop problem" => "tutorials/PaintShop.md",
-            "Coloring problem" => "tutorials/Coloring.md",
-            "Dominating set problem" => "tutorials/DominatingSet.md",
-            "Satisfiability problem" => "tutorials/Satisfiability.md",
-            "Set covering problem" => "tutorials/SetCovering.md",
-            "Set packing problem" => "tutorials/SetPacking.md",
-            #"Other problems" => "tutorials/Others.md",
+            "Independent set problem" => "generated/IndependentSet.md",
+            "Maximal independent set problem" => "generated/MaximalIS.md",
+            "Cutting problem" => "generated/MaxCut.md",
+            "Vertex Matching problem" => "generated/Matching.md",
+            "Binary paint shop problem" => "generated/PaintShop.md",
+            "Coloring problem" => "generated/Coloring.md",
+            "Dominating set problem" => "generated/DominatingSet.md",
+            "Satisfiability problem" => "generated/Satisfiability.md",
+            "Set covering problem" => "generated/SetCovering.md",
+            "Set packing problem" => "generated/SetPacking.md",
+            #"Other problems" => "generated/Others.md",
         ],
         "Topics" => [
-            "Make extensions" => "extension.md",
-            "Save and load solutions" => "tutorials/saveload.md",
+            "Gist" => "gist.md",
+            "Save and load solutions" => "generated/saveload.md",
             "Sum product tree representation" => "sumproduct.md",
-            "Weighted problems" => "tutorials/weighted.md",
-            "Open degree of freedoms" => "tutorials/open.md"
+            "Weighted problems" => "generated/weighted.md",
+            "Open and fixed degrees of freedom" => "generated/open.md"
         ],
         "Performance Tips" => "performancetips.md",
         "References" => "ref.md",

docs/serve.jl

@@ -10,7 +10,7 @@ function serve(;host::String="0.0.0.0", port::Int=8000)
         doc_env=true,
         skip_dirs=[
             joinpath("docs", "src", "assets"),
-            joinpath("docs", "src", "tutorials"),
+            joinpath("docs", "src", "generated"),
         ],
         literate="examples",
         host=\"$host\",

docs/src/generated/Coloring.md

@@ -0,0 +1,103 @@
+```@meta
+EditURL = "<unknown>/examples/Coloring.jl"
+```
+
+# Coloring problem
+
+!!! note
+    It is highly recommended to read the [Independent set problem](@ref) chapter before reading this one.
+
+## Problem definition
+A [vertex coloring](https://en.wikipedia.org/wiki/Graph_coloring) is an assignment of labels or colors to each vertex of a graph such that no edge connects two identically colored vertices.
+In the following, we are going to defined a 3-coloring problem for the Petersen graph.
+
+````@example Coloring
+using GenericTensorNetworks, Graphs
+
+graph = Graphs.smallgraph(:petersen)
+````
+
+We can visualize this graph using the following function
+
+````@example Coloring
+rot15(a, b, i::Int) = cos(2i*π/5)*a + sin(2i*π/5)*b, cos(2i*π/5)*b - sin(2i*π/5)*a
+
+locations = [[rot15(0.0, 1.0, i) for i=0:4]..., [rot15(0.0, 0.6, i) for i=0:4]...]
+
+show_graph(graph; locs=locations)
+````
+
+## Generic tensor network representation
+
+We construct the tensor network for the 3-coloring problem as
+
+````@example Coloring
+problem = Coloring{3}(graph);
+nothing #hide
+````
+
+### Theory (can skip)
+Type [`Coloring`](@ref) can be used for constructing the tensor network with optimized contraction order for a coloring problem.
+Let us use 3-colouring problem defined on vertices as an example.
+For a vertex ``v``, we define the degrees of freedom ``c_v\in\{1,2,3\}`` and a vertex tensor labelled by it as
+```math
+W(v) = \left(\begin{matrix}
+    1\\
+    1\\
+    1
+\end{matrix}\right).
+```
+For an edge ``(u, v)``, we define an edge tensor as a matrix labelled by ``(c_u, c_v)`` to specify the constraint
+```math
+B = \left(\begin{matrix}
+    1 & x & x\\
+    x & 1 & x\\
+    x & x & 1
+\end{matrix}\right).
+```
+The number of possible colouring can be obtained by contracting this tensor network by setting vertex tensor elements ``r_v, g_v`` and ``b_v`` to 1.
+
+## Solving properties
+##### counting all possible coloring
+
+````@example Coloring
+num_of_coloring = solve(problem, CountingMax())[]
+````
+
+##### finding one best coloring
+
+````@example Coloring
+single_solution = solve(problem, SingleConfigMax())[]
+
+is_vertex_coloring(graph, single_solution.c.data)
+
+vertex_color_map = Dict(0=>"red", 1=>"green", 2=>"blue")
+
+show_graph(graph; locs=locations, vertex_colors=[vertex_color_map[Int(c)]
+     for c in single_solution.c.data])
+````
+
+Let us try to solve the same issue on its line graph, a graph that generated by mapping an edge to a vertex and two edges sharing a common vertex will be connected.
+
+````@example Coloring
+linegraph = line_graph(graph)
+
+show_graph(linegraph; locs=[0.5 .* (locations[e.src] .+ locations[e.dst])
+     for e in edges(graph)])
+````
+
+Let us construct the tensor network and see if there are solutions.
+
+````@example Coloring
+lineproblem = Coloring{3}(linegraph);
+
+num_of_coloring = solve(lineproblem, CountingMax())[]
+````
+
+You will see the maximum size 28 is smaller than the number of edges in the `linegraph`,
+meaning no solution for the 3-coloring on edges of a Petersen graph.
+
+---
+
+*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
+

docs/src/generated/DominatingSet.md

@@ -0,0 +1,109 @@
+```@meta
+EditURL = "<unknown>/examples/DominatingSet.jl"
+```
+
+# Dominating set problem
+
+!!! note
+    It is highly recommended to read the [Independent set problem](@ref) chapter before reading this one.
+
+## Problem definition
+
+In graph theory, a [dominating set](https://en.wikipedia.org/wiki/Dominating_set) for a graph ``G = (V, E)`` is a subset ``D`` of ``V`` such that every vertex not in ``D`` is adjacent to at least one member of ``D``.
+The domination number ``\gamma(G)`` is the number of vertices in a smallest dominating set for ``G``.
+The decision version of finding the minimum dominating set is an NP-complete.
+In the following, we are going to solve the dominating set problem on the Petersen graph.
+
+````@example DominatingSet
+using GenericTensorNetworks, Graphs
+
+graph = Graphs.smallgraph(:petersen)
+````
+
+We can visualize this graph using the following function
+
+````@example DominatingSet
+rot15(a, b, i::Int) = cos(2i*π/5)*a + sin(2i*π/5)*b, cos(2i*π/5)*b - sin(2i*π/5)*a
+
+locations = [[rot15(0.0, 1.0, i) for i=0:4]..., [rot15(0.0, 0.6, i) for i=0:4]...]
+
+show_graph(graph; locs=locations)
+````
+
+## Generic tensor network representation
+We can use [`DominatingSet`](@ref) to construct the tensor network for solving the dominating set problem as
+
+````@example DominatingSet
+problem = DominatingSet(graph; optimizer=TreeSA());
+nothing #hide
+````
+
+### Theory (can skip)
+Let ``G=(V,E)`` be the target graph that we want to solve.
+The tensor network representation map a vertex ``v\in V`` to a boolean degree of freedom ``s_v\in\{0, 1\}``.
+We defined the restriction on a vertex and its neighbouring vertices ``N(v)``:
+```math
+T(x_v)_{s_1,s_2,\ldots,s_{|N(v)|},s_v} = \begin{cases}
+    0 & s_1=s_2=\ldots=s_{|N(v)|}=s_v=0,\\
+    1 & s_v=0,\\
+    x_v^{w_v} & \text{otherwise},
+\end{cases}
+```
+where ``w_v`` is the weight of vertex ``v``.
+This tensor means if both ``v`` and its neighbouring vertices are not in ``D``, i.e., ``s_1=s_2=\ldots=s_{|N(v)|}=s_v=0``,
+this configuration is forbidden because ``v`` is not adjacent to any member in the set.
+otherwise, if ``v`` is in ``D``, it has a contribution ``x_v^{w_v}`` to the final result.
+One can check the contraction time space complexity of a [`DominatingSet`](@ref) instance by typing:
+
+````@example DominatingSet
+timespacereadwrite_complexity(problem)
+````
+
+## Solving properties
+
+### Counting properties
+##### Domination polynomial
+The graph polynomial for the dominating set problem is known as the domination polynomial (see [arXiv:0905.2251](https://arxiv.org/abs/0905.2251)).
+It is defined as
+```math
+D(G, x) = \sum_{k=0}^{\gamma(G)} d_k x^k,
+```
+where ``d_k`` is the number of dominating sets of size ``k`` in graph ``G=(V, E)``.
+
+````@example DominatingSet
+domination_polynomial = solve(problem, GraphPolynomial())[]
+````
+
+The domination number ``\gamma(G)`` can be computed with the [`SizeMin`](@ref) property:
+
+````@example DominatingSet
+domination_number = solve(problem, SizeMin())[]
+````
+
+Similarly, we have its counting [`CountingMin`](@ref):
+
+````@example DominatingSet
+counting_min_dominating_set = solve(problem, CountingMin())[]
+````
+
+### Configuration properties
+##### finding minimum dominating set
+One can enumerate all minimum dominating sets with the [`ConfigsMin`](@ref) property in the program.
+
+````@example DominatingSet
+min_configs = solve(problem, ConfigsMin())[].c
+
+all(c->is_dominating_set(graph, c), min_configs)
+````
+
+````@example DominatingSet
+show_gallery(graph, (2, 5); locs=locations, vertex_configs=min_configs)
+````
+
+Similarly, if one is only interested in computing one of the minimum dominating sets,
+one can use the graph property [`SingleConfigMin`](@ref).
+
+---
+
+*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
+