fix docs

Author: GiggleLiu

docs/src/performancetips.md

@@ -23,7 +23,7 @@ Other optimizers include
 One can type `?TreeSA` in a Julia REPL for more information about how to configure the hyper-parameters of `TreeSA` method.
 `simplifier` keyword argument is not so important, it is a preprocessing routine to improve the searching speed of the `optimizer`.
 
-The returned instance `problem` contains a field `code` that specifies the tensor network contraction order. For an independence problem, 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``.
+The returned instance `problem` contains a field `code` that specifies the tensor network contraction order. For an independent set problem, 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.
 
 ```julia

examples/IndependentSet.jl

@@ -16,40 +16,40 @@ 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.
+# Let ``G=(V,E)`` be the target graph that we want to solve.
+# The tensor network representation map a vertex ``i\in V`` to a label ``s_i \in \{0, 1\}`` of dimension ``2`` in a tensor network, 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``.
+# \begin{equation}
+#     W(x_i) = \left(\begin{matrix}
+#         1 \\
+#         x_i
+#     \end{matrix}\right).
+# \end{equation}
+# 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.
+# \begin{equation}
+#     \qquad \quad 
+#        B = \left(\begin{matrix}
+#         1  & 1\\
+#         1 & 0
+#     \end{matrix}\right). \label{eq:edgetensor}
+# \end{equation}
+
+# We can use [`IndependentSet`](@ref) to construct a tensor network
+# corresponding to the independent set problem on our target graph.
 problem = IndependentSet(graph; optimizer=TreeSA());
 
-# In the input arguments of [`IndependentSet`](@ref), the `optimizer` is for optimizing the contraction orders.
-# Here we use the local search based optimizer `TreeSA`.
-# The returned instance `problem` contains a field `code` that specifies the tensor network contraction order.
+# Key word argument `optimizer` specifies the contraction order optimizer of the tensor network.
+# Here we use the local search based optimizer [`TreeSA`](@ref).
+# The return value `problem` contains a field `code` that specifies the tensor network and its contraction order.
 # The optimal contraction time and space complexity of an independent set problem 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)
 
-# The return values are `log2` of the the number of iterations, the number elements in the max tensor and the number of read-write operations to tensor elements.
-# For more information about the performance, please check the [Performance Tips](@ref).
-
+# The return values are `log2` of the the number of iterations, the number elements in the tensor with maximum size during contraction and the number of tensor element read-write operations.
+# For more information about how to improve the contraction order, please check the [Performance Tips](@ref).
 
 # ## Solving properties
 
@@ -64,12 +64,12 @@ count_all_independent_sets = solve(problem, CountingAll())[]
 count_max2_independent_sets = solve(problem, CountingMax(2))[]
 
 # ##### independence polynomial
-# The graph polynomial defined for the independence problem is known as the independence polynomial.
+# The graph polynomial for the independent set 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)``.
+# ``a_k`` is the number of independent sets of size ``k``.
 # 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).
@@ -80,7 +80,7 @@ independence_polynomial = solve(problem, GraphPolynomial(; method=:finitefield))
 # There are two approaches to find one of the best solution.
 # The unbounded (default) version uses [`ConfigSampler`](@ref) to sample one of the best solutions directly.
 # The bounded version uses the binary gradient back-propagation (see our paper) to compute the gradients.
-# It requires caching intermediate states, but is often faster on CPU because it can use [`TropicalGEMM`](https://github.com/TensorBFS/TropicalGEMM.jl).
+# It requires caching intermediate states, but is often faster (on CPU) because it can use [`TropicalGEMM`](https://github.com/TensorBFS/TropicalGEMM.jl) (see [Performance Tips](@ref)).
 max_config = solve(problem, SingleConfigMax(; bounded=false))[]
 
 # The return value contains a bit string, and one should read this bit string from left to right.
@@ -132,14 +132,14 @@ max_config_weighted = solve(problem, SingleConfigMax())[]
 show_graph(graph; locs=locations, vertex_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.
+# The following code computes the MIS tropical tensor (reference to be added) with open vertices 1, 2 and 3.
 problem = IndependentSet(graph; openvertices=[1,2,3])
 
 mis_tropical_tensor = solve(problem, SizeMax())
 
 # The MIS tropical tensor shows the MIS size under different configuration of open vertices.
 # It is useful in MIS tropical tensor analysis.
-# One can compatify this MIS-Tropical tensor by typing
+# One can compatify (reference to be added) this MIS-Tropical tensor by typing
 
 mis_compactify!(mis_tropical_tensor)
 

examples/Matching.jl

@@ -54,7 +54,7 @@ max_matching = solve(problem, SizeMax())[]
 # The largest number of matching is 5, which means we have a perfect matching (vertices are all paired).
 
 # ##### matching polynomial
-# The graph polynomial defined for the independence problem is known as the matching polynomial.
+# The graph polynomial defined for the matching 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,

examples/PaintShop.jl

@@ -64,7 +64,7 @@ show_graph(graph; locs=locations, texts=string.(sequence), edge_colors=
 problem = PaintShop(sequence);
 
 # ### Counting properties
-# ##### maximal independence polynomial
+# ##### graph polynomial
 # The graph polynomial defined for the maximal independent set problem is
 # ```math
 # I_{\rm max}(G, x) = \sum_{k=0}^{\alpha(G)} b_k x^k,

test/interfaces.jl

@@ -1,7 +1,7 @@
 using GraphTensorNetworks
 using Graphs, Test
 
-@testset "independence problem" begin
+@testset "independent set problem" begin
     g = Graphs.smallgraph("petersen")
     for optimizer in (GreedyMethod(), TreeSA(ntrials=1))
         gp = IndependentSet(g; optimizer=optimizer)