Polish docs 1 (#12)

* rename independence

* rename independence

Author: GiggleLiu

README.md

@@ -50,15 +50,15 @@ julia> using GraphTensorNetworks, Random, Graphs
 julia> graph = (Random.seed!(2); Graphs.smallgraph(:petersen))
 {10, 15} undirected simple Int64 graph
 
-julia> problem = Independence(graph; optimizer=TreeSA(sc_target=0, sc_weight=1.0, ntrials=10, βs=0.01:0.1:15.0, niters=20, rw_weight=0.2));
+julia> problem = IndependentSet(graph; optimizer=TreeSA(sc_target=0, sc_weight=1.0, ntrials=10, βs=0.01:0.1:15.0, niters=20, rw_weight=0.2));
 ┌ Warning: target space complexity not found, got: 4.0, with time complexity 7.965784284662087, read-right complexity 8.661778097771988.
 └ @ OMEinsumContractionOrders ~/.julia/dev/OMEinsumContractionOrders/src/treesa.jl:71
 time/space complexity is (7.965784284662086, 4.0)
 ```
 
-Here, the `problem` is a `Independence` instance, it contains the tensor network contraction tree for the target graph.
+Here, the `problem` is a `IndependentSet` instance, it contains the tensor network contraction tree for the target graph.
 Here, we choose the `TreeSA` optimizer to optimize the tensor network contraciton tree, it is a local search based algorithm, check [arXiv: 2108.05665](https://arxiv.org/abs/2108.05665). You will see some warnings, do not panic, this is because we set `sc_target` (target space complex) to 1 for agressive optimization of space complexity. Type `?TreeSA` in a Julia REPL for more information about the key word arguments.
-Similarly, one can select tensor network structures for solving other problems like `MaximalIndependence`, `MaxCut`, `Matching`, `Coloring{K}`, `PaintShop` and `set_packing`.
+Similarly, one can select tensor network structures for solving other problems like `MaximalIS`, `MaxCut`, `Matching`, `Coloring{K}`, `PaintShop` and `set_packing`.
 
 #### 1. find MIS size, count MISs and count ISs
 ```julia

docs/make.jl

@@ -6,13 +6,12 @@ using DocThemeIndigo
 using Literate
 
 for each in readdir(pkgdir(GraphTensorNetworks, "examples"))
-    project_dir = pkgdir(GraphTensorNetworks, "examples", each)
-    isdir(project_dir) || continue
-    @info "building" project_dir
-    input_file = pkgdir(GraphTensorNetworks, "examples", each, "main.jl")
+    input_file = pkgdir(GraphTensorNetworks, "examples", each)
+    endswith(input_file, ".jl") || continue
+    @info "building" input_file
     output_dir = pkgdir(GraphTensorNetworks, "docs", "src", "tutorials")
     @info "executing" input_file
-    Literate.markdown(input_file, output_dir; name=each, execute=false)
+    Literate.markdown(input_file, output_dir; name=each[1:end-3], execute=false)
 end
 
 indigo = DocThemeIndigo.install(GraphTensorNetworks)
@@ -24,17 +23,17 @@ makedocs(;
     repo="https://github.com/Happy-Diode/GraphTensorNetworks.jl/blob/{commit}{path}#{line}",
     sitename="GraphTensorNetworks.jl",
     format=Documenter.HTML(;
-        prettyurls=get(ENV, "CI", "false") == "true",
+        prettyurls=false,
         canonical="https://Happy-Diode.github.io/GraphTensorNetworks.jl",
         assets=String[indigo],
     ),
     pages=[
         "Home" => "index.md",
         "Tutorials" => [
-            "Independent set problem" => "tutorials/Independence.md",
-            "Maximal independent set problem" => "tutorials/MaximalIndependence.md",
+            "Independent set problem" => "tutorials/IndependentSet.md",
+            "Maximal independent set problem" => "tutorials/MaximalIS.md",
             "Cutting problem" => "tutorials/MaxCut.md",
-            "Matching problem" => "tutorials/Coloring.md",
+            "Matching problem" => "tutorials/Matching.md",
             "Binary paint shop problem" => "tutorials/PaintShop.md",
             "Coloring problem" => "tutorials/Coloring.md",
             "Other problems" => "tutorials/Others.md",

docs/src/ref.md

@@ -3,8 +3,8 @@
 ```@docs
 solve
 GraphProblem
-Independence
-MaximalIndependence
+IndependentSet
+MaximalIS
 Matching
 Coloring
 MaxCut

examples/Coloring.jl

@@ -0,0 +1,50 @@
+# # Coloring problem
+
+# !!! note
+#     This tutorial only covers the coloring problem specific features,
+#     It is recommended to read the [Independent set problem](@ref) tutorial too to know more about
+#     * how to optimize the tensor network contraction order,
+#     * what are the other graph properties computable,
+#     * how to select correct method to compute graph properties,
+#     * how to compute weighted graphs and handle open vertices.
+
+# ## 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.
+
+using GraphTensorNetworks, Graphs
+
+graph = Graphs.smallgraph(:petersen)
+
+# We can visualize this graph using the following function
+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)
+
+# ## Tensor network representation
+# 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 degree of freedoms ``c_v\in\{1,2,3\}`` and a vertex tensor labelled by it as
+# ```math
+# W(v) = \left(\begin{matrix}
+#     r_v\\
+#     g_v\\
+#     b_v
+# \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}
+#     0 & 1 & 1\\
+#     1 & 0 & 1\\
+#     1 & 1 & 0
+# \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.
+#
+# We construct the tensor network for the 3-coloring problem as
+problem = Coloring{3}(graph);
+
+# ## Solving properties

examples/Coloring/main.jl

@@ -1,13 +1,11 @@
 # # Independent set problem
 
-# ## Introduction
-using GraphTensorNetworks, Graphs
-
-# Please check the docstring of [`Independence`](@ref) for the definition of independence problem.
-@doc Independence
-
+# ## Problem definition
+# In graph theory, an [independent set](https://en.wikipedia.org/wiki/Independent_set_(graph_theory)) is a set of vertices in a graph, no two of which are adjacent.
 # In the following, we are going to defined an independent set problem for the Petersen graph.
 
+using GraphTensorNetworks, Graphs
+
 graph = Graphs.smallgraph(:petersen)
 
 # We can visualize this graph using the following function
@@ -17,17 +15,38 @@ 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)
 
+# ## Tensor network representation
+# Type [`IndependentSet`](@ref) can be used for constructing the tensor network with optimized contraction order for solving an independent set problem.
+# we map a vertex ``i\in V`` to a label ``s_i \in \{0, 1\}`` of dimension 2,
+# where we use 0 (1) to denote a vertex is absent (present) in the set.
+# For each label ``s_i``, we defined a parametrized rank-one vertex tensor ``W(x_i)`` as
+# ```math
+# W(x_i)_{s_i} = \left(\begin{matrix}
+#     1 \\
+#     x_i
+# \end{matrix}\right)_{s_i}
+# ```
+# We use subscripts to index tensor elements, e.g.``W(x_i)_0=1`` is the first element associated
+# with ``s_i=0`` and ``W(x_i)_1=x_i`` is the second element associated with ``s_i=1``.
+# Similarly, on each edge ``(u, v)``, we define a matrix ``B`` indexed by ``s_u`` and ``s_v`` as
+# ```math
+# B_{s_i s_j} = \left(\begin{matrix}
+#     1  & 1\\
+#     1 & 0
+# \end{matrix}\right)_{s_is_j}
+# ```
 # Let us contruct the problem instance with optimized tensor network contraction order as bellow.
-problem = Independence(graph; optimizer=TreeSA(sc_weight=1.0, ntrials=10,
+problem = IndependentSet(graph; optimizer=TreeSA(sc_weight=1.0, ntrials=10,
                          βs=0.01:0.1:15.0, niters=20, rw_weight=0.2),
                          simplifier=MergeGreedy());
 
-# The `optimizer` is for optimizing the contraction orders.
+# In the input arguments of [`IndependentSet`](@ref), the `optimizer` is for optimizing the contraction orders.
 # Here we use the local search based optimizer in [arXiv:2108.05665](https://arxiv.org/abs/2108.05665).
 # If no optimizer is specified, the default fast (in terms of the speed of searching contraction order)
 # but worst (in term of contraction complexity) [`GreedyMethod`](@ref) will be used.
 # `simplifier` is a preprocessing routine to speed up the `optimizer`.
-# Please check section [Tensor Network](@ref) for more details.
+# The returned instance `problem` contains a field `code` that specifies the tensor network contraction order.
+# Its contraction time space complexity is ``2^{{\rm tw}(G)}``, where ``{\rm tw(G)}`` is the [tree-width](https://en.wikipedia.org/wiki/Treewidth) of ``G``.
 # One can check the time, space and read-write complexity with the following function.
 
 timespacereadwrite_complexity(problem)
@@ -48,7 +67,13 @@ count_all_independent_sets = solve(problem, CountingAll())[]
 count_max2_independent_sets = solve(problem, CountingMax(2))[]
 
 # ##### independence polynomial
-# For the definition of independence polynomial, please check the docstring of [`Independence`](@ref) or this [wiki page](https://mathworld.wolfram.com/IndependencePolynomial.html).
+# The graph polynomial defined for the independence problem is known as the independence polynomial.
+# ```math
+# I(G, x) = \sum_{k=0}^{\alpha(G)} a_k x^k,
+# ```
+# where ``\alpha(G)`` is the maximum independent set size, 
+# ``a_k`` is the number of independent sets of size ``k`` in graph ``G=(V,E)``.
+# The total number of independent sets is thus equal to ``I(G, 1)``.
 # There are 3 methods to compute a graph polynomial, `:finitefield`, `:fft` and `:polynomial`.
 # These methods are introduced in the docstring of [`GraphPolynomial`](@ref).
 independence_polynomial = solve(problem, GraphPolynomial(; method=:finitefield))[]
@@ -98,17 +123,17 @@ loaded_sets = load_configs(filename; format=:binary, bitlength=10)
 #     Because the bitstring length is not stored.
 
 # ## Weights and open vertices
-# [`Independence`] accepts weights as a key word argument.
+# [`IndependentSet`] accepts weights as a key word argument.
 # The following code computes the weighted MIS problem.
-problem = Independence(graph; weights=collect(1:10))
+problem = IndependentSet(graph; weights=collect(1:10))
 
 max_config_weighted = solve(problem, SingleConfigMax())[]
 
 show_graph(graph; locs=locations, colors=
           [iszero(max_config_weighted.c.data[i]) ? "white" : "red" for i=1:nv(graph)])
 
 # The following code computes the MIS tropical tensor (reference to be added) with open vertices 1 and 2.
-problem = Independence(graph; openvertices=[1,2,3])
+problem = IndependentSet(graph; openvertices=[1,2,3])
 
 mis_tropical_tensor = solve(problem, SizeMax())
 

examples/Independence/main.jl renamed to examples/IndependentSet.jl

@@ -0,0 +1,56 @@
+# # Vertex matching problem
+
+# !!! note
+#     This tutorial only covers the vertex matching problem specific features,
+#     It is recommended to read the [Independent set problem](@ref) tutorial too to know more about
+#     * how to optimize the tensor network contraction order,
+#     * what are the other graph properties computable,
+#     * how to select correct method to compute graph properties,
+#     * how to compute weighted graphs and handle open vertices.
+
+# ## Problem definition
+# A ``k``-matching in a graph ``G`` is a set of k edges, no two of which have a vertex in common.
+
+using GraphTensorNetworks, Graphs
+
+# In the following, we are going to defined a matching problem for the Petersen graph.
+
+graph = Graphs.smallgraph(:petersen)
+
+# We can visualize this graph using the following function
+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)
+
+# ## Tensor network representation
+# Type [`Matching`](@ref) can be used for constructing the tensor network with optimized contraction order for a matching problem.
+# We map an edge ``(u, v) \in E`` to a label ``\langle u, v\rangle \in \{0, 1\}`` in a tensor network,
+# where 1 means two vertices of an edge are matched, 0 means otherwise.
+# Then we define a tensor of rank ``d(v) = |N(v)|`` on vertex ``v`` such that,
+# ```math
+# W_{\langle v, n_1\rangle, \langle v, n_2 \rangle, \ldots, \langle v, n_{d(v)}\rangle} = \begin{cases}
+#     1, & \sum_{i=1}^{d(v)} \langle v, n_i \rangle \leq 1,\\
+#     0, & \text{otherwise},
+# \end{cases}
+# ```
+# and a tensor of rank 1 on the bond
+# ```math
+# B_{\langle v, w\rangle} = \begin{cases}
+# 1, & \langle v, w \rangle = 0 \\
+# x, & \langle v, w \rangle = 1,
+# \end{cases}
+# ```
+# where label ``\langle v, w \rangle`` is equivalent to ``\langle w,v\rangle``.
+#
+# We construct the tensor network for the matching problem by typing
+problem = Matching(graph);
+
+# ## Solving properties
+# The graph polynomial defined for the independence problem is known as the matching polynomial.
+# Here, we adopt the first definition in the [wiki page](https://en.wikipedia.org/wiki/Matching_polynomial).
+# ```math
+# M(G, x) = \sum\limits_{k=1}^{|V|/2} c_k x^k,
+# ```
+# where ``k`` is the number of matches, and coefficients ``c_k`` are the corresponding counting.