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

Author: GiggleLiu

.github/workflows/CI.yml

@@ -5,7 +5,25 @@ on:
       - master
   pull_request:
 jobs:
+  pre_job:
+    # continue-on-error: true # Uncomment once integration is finished
+    runs-on: ubuntu-latest
+    # Map a step output to a job output
+    outputs:
+      should_skip: ${{ steps.skip_check.outputs.should_skip }}
+    steps:
+      - id: skip_check
+        uses: fkirc/skip-duplicate-actions@master
+        with:
+          # All of these options are optional, so you can remove them if you are happy with the defaults
+          concurrent_skipping: 'never'
+          skip_after_successful_duplicate: 'true'
+          paths_ignore: '["**/README.md", "**/docs/**", "**/examples/**"]'
+          do_not_skip: '["pull_request", "workflow_dispatch", "schedule"]'
+
   test:
+    needs: pre_job
+    if: ${{ needs.pre_job.outputs.should_skip != 'true' }}
     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
     runs-on: ${{ matrix.os }}
     strategy:
@@ -44,8 +62,9 @@ jobs:
           path-to-lcov: lcov.info
 
   finish:
+      needs: [pre_job, test]
+      if: ${{ needs.pre_job.outputs.should_skip != 'true' }}
       name: Coveralls Finished
-      needs: test
       runs-on: ubuntu-latest
       steps:
         - uses: coverallsapp/github-action@master

README.md

@@ -8,25 +8,34 @@
 <p>
 GraphTensorNetworks is a &nbsp;
     <a href="https://julialang.org">
-        <img src="https://julialang.org/favicon.ico" width="16em">
+        <img src="https://raw.githubusercontent.com/JuliaLang/julia-logo-graphics/master/images/julia.ico" width="16em">
         Julia Language
     </a>
     &nbsp; package. To install GraphTensorNetworks,
     please <a href="https://docs.julialang.org/en/v1/manual/getting-started/">open
     Julia's interactive session (known as REPL)</a> and press <kbd>]</kbd> key in the REPL to use the package mode, then
 </p>
 
-1. if you have access to our registry
+1. if you are a user, just type
 ```julia
 pkg> add GraphTensorNetworks
 ```
 
-2. otherwise (e.g. if you are an external collaborator), you can install in develop mode
+If you do not have access to our registry, e.g. you are an external collaborator, you can install the master branch by typing
+```julia
+pkg> add https://github.com/Happy-Diode/GraphTensorNetworks.jl.git#master
+```
+
+To update, just type `up` in the package mode.
+
+2. If you are a developer, you can install it in develop mode
 ```julia
 pkg> dev https://github.com/Happy-Diode/GraphTensorNetworks.jl.git
 ```
 
-Please use **Julia-1.7**, otherwise you will suffer from huge overheads when contracting large tensor networks. If you have to use a lower version,
+Packages installed in developer mode will not be updated by the `up` command, you should go to the develop folder and use `git` to manage your versions. For more [details](https://docs.julialang.org/en/v1/stdlib/Pkg/).
+
+Please use **Julia version >= 1.7**, otherwise you will suffer from huge overheads when contracting large tensor networks. If you have to use an old version Julia,
 you can avoid the overhead by overriding the `permutedims!` is `LinearAlgebra`, i.e. add the following code to your own project.
 
 ```julia
@@ -43,7 +52,7 @@ end
 
 ## Examples
 
-Let us use the Petersen graph as an example, we first generate its tensor network contraction tree.
+In this example, we will show how to compute the independent set properties of the Petersen graph, we first generate its tensor network contraction tree.
 ```julia
 julia> using GraphTensorNetworks, Random, Graphs
 
@@ -83,9 +92,8 @@ julia> solve(problem, CountingMax(2))[]
 30.0*x^3 + 5.0*x^4
 ```
 
-#### 2. compute the independence polynomial
-
 The following code computes independence polynomial using the finite field algebra (default) approach.
+It is equivalent to counting independent sets of an arbituary size.
 
 ```julia
 julia> solve(problem, GraphPolynomial())[]

docs/src/performancetips.md

@@ -28,9 +28,31 @@ One can check the time, space and read-write complexity with the following funct
 
 ```julia
 julia> timespacereadwrite_complexity(problem)
+(21.90683335864693, 17.0, 20.03588509836998)
 ```
 
-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.
+The return values are `log2` of the the number of iterations, the number elements in the largest tensor during contraction and the number of read-write operations to tensor elements.
+In this example, the number of `+` and `*` operations are both `\sim 2^{21.9}`
+and the number of read-write operations are `\sim 2^{20}`.
+The largest tensor size is ``2^17``, one can check the element size by typing
+```julia
+julia> sizeof(TropicalF64)
+8
+
+julia> sizeof(TropicalF32)
+4
+
+julia> sizeof(StaticBitVector{200,4})
+32
+
+julia> sizeof(TruncatedPoly{5,Float64,Float64})
+48
+```
+
+!!! note
+    * The actual run time memory can be several times larger than the size of the maximum tensor.
+    There is no constant bound for the factor, an empirical value for it is 3x.
+    * For mutable types like [`Polynomial`](@ref) and [`ConfigEnumerater`](@ref), the `sizeof` function does not measure the actual element size.
 
 ## GEMM for Tropical numbers
 You can speed up the Tropical number matrix multiplication when computing `SizeMax()` by using the Tropical GEMM routines implemented in package [`TropicalGEMM.jl`](https://github.com/TensorBFS/TropicalGEMM.jl/).

examples/IndependentSet.jl

@@ -15,6 +15,13 @@ 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)
 
+# In order to display your plot with [`show_graph`](@ref), you need to call this function in
+# * a [VSCode](https://github.com/julia-vscode/julia-vscode) editor,
+# * a [Jupyter](https://github.com/JunoLab/Juno.jl) notebook,
+# * or a [Pluto](https://github.com/fonsp/Pluto.jl) notebook,
+#
+# rather than a Julia REPL that does not have a graphical display.
+
 # ## Tensor network representation
 # 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.
@@ -47,7 +54,7 @@ problem = IndependentSet(graph; optimizer=TreeSA());
 
 timespacereadwrite_complexity(problem)
 
-# 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.
+# The return values are `log2` of the the number of iterations, the number elements in the largest tensor 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

examples/PaintShop.jl

@@ -45,16 +45,18 @@ show_graph(graph; locs=locations, texts=string.(sequence), edge_colors=
 # For each black edges ``(i, i+1)``, we define an edge tensor labeld by ``(s_{c_i}, s_{c_{i+1}})`` as follows:
 # If both cars on this edge are their first or second appearance
 # ```math
-# B^{\rm parallel} = \begin{matrix}
+# B^{\rm parallel} = \left(\begin{matrix}
 # x & 1 \\
 # 1 & x \\
-# \end{matrix},
+# \end{matrix}\right),
+# ```
 #
 # otherwise,
-# B^{\rm anti-parallel} = B^{\rm 10} = \begin{matrix}
+# ```math
+# B^{\rm anti-parallel} = \left(\begin{matrix}
 # 1 & x \\
 # x & 1 \\
-# \end{matrix}.
+# \end{matrix}\right).
 # ```
 # It can be understood as, when both cars are their first appearance,
 # they tend to have the same configuration so that the color is not changed.

src/arithematics.jl

@@ -78,12 +78,21 @@ end
 
 """
     TruncatedPoly{K,T,TO} <: Number
+    TruncatedPoly(coeffs::Tuple, maxorder)
 
 Polynomial truncated to largest `K` orders. `T` is the coefficients type and `TO` is the orders type.
 
+Example
+------------------------
 ```jldoctest; setup=(using GraphTensorNetworks)
 julia> TruncatedPoly((1,2,3), 6)
 x^4 + 2*x^5 + 3*x^6
+
+julia> TruncatedPoly((1,2,3), 6) * TruncatedPoly((5,2,1), 3)
+20*x^7 + 8*x^8 + 3*x^9
+
+julia> TruncatedPoly((1,2,3), 6) + TruncatedPoly((5,2,1), 3)
+x^4 + 2*x^5 + 3*x^6
 ```
 """
 struct TruncatedPoly{K,T,TO} <: Number
@@ -93,6 +102,9 @@ end
 
 """
     Max2Poly{T,TO} = TruncatedPoly{2,T,TO}
+    Max2Poly(a, b, maxorder)
+
+A shorthand of [`TruncatedPoly`](@ref){2}.
 """
 const Max2Poly{T,TO} = TruncatedPoly{2,T,TO}
 Max2Poly(a, b, maxorder) = TruncatedPoly((a, b), maxorder)
@@ -157,6 +169,8 @@ Set algebra for enumerating configurations, where `N` is the length of configura
 `C` is the size of storage in unit of `UInt64`,
 `S` is the bit width to store a single element in a configuration, i.e. `log2(# of flavors)`, for bitstrings, it is `1``.
 
+Example
+----------------------
 ```jldoctest; setup=:(using GraphTensorNetworks)
 julia> a = ConfigEnumerator([StaticBitVector([1,1,1,0,0]), StaticBitVector([1,0,0,0,1])])
 {11100, 10001}
@@ -166,6 +180,12 @@ julia> b = ConfigEnumerator([StaticBitVector([0,0,0,0,0]), StaticBitVector([1,0,
 
 julia> a + b
 {11100, 10001, 00000, 10101}
+
+julia> one(a)
+{00000}
+
+julia> zero(a)
+{}
 ```
 """
 struct ConfigEnumerator{N,S,C}
@@ -203,14 +223,32 @@ Base.show(io::IO, ::MIME"text/plain", x::ConfigEnumerator) = Base.show(io, x)
 # the algebra sampling one of the configurations
 """
     ConfigSampler{N,S,C}
+    ConfigSampler(elements::StaticElementVector)
 
 The algebra for sampling one configuration, where `N` is the length of configurations,
 `C` is the size of storage in unit of `UInt64`,
 `S` is the bit width to store a single element in a configuration, i.e. `log2(# of flavors)`, for bitstrings, it is `1``.
 
-```jldoctest; setup=:(using GraphTensorNetworks)
+!!! note
+    `ConfigSampler` is a **probabilistic** commutative semiring, adding two config samplers do not give you deterministic results.
+
+Example
+----------------------
+```jldoctest; setup=:(using GraphTensorNetworks, Random; Random.seed!(2))
 julia> ConfigSampler(StaticBitVector([1,1,1,0,0]))
 ConfigSampler{5, 1, 1}(11100)
+
+julia> ConfigSampler(StaticBitVector([1,1,1,0,0])) + ConfigSampler(StaticBitVector([1,0,1,0,0]))
+ConfigSampler{5, 1, 1}(10100)
+
+julia> ConfigSampler(StaticBitVector([1,1,1,0,0])) * ConfigSampler(StaticBitVector([0,0,0,0,1]))
+ConfigSampler{5, 1, 1}(11101)
+
+julia> one(ConfigSampler{5, 1, 1})
+ConfigSampler{5, 1, 1}(00000)
+
+julia> zero(ConfigSampler{5, 1, 1})
+ConfigSampler{5, 1, 1}(11111)
 ```
 """
 struct ConfigSampler{N,S,C}

src/bitvector.jl

@@ -1,9 +1,20 @@
 """
     StaticElementVector{N,S,C}
+    StaticElementVector(nflavor::Int, x::AbstractVector)
 
 `N` is the length of vector, `C` is the size of storage in unit of `UInt64`,
 `S` is the stride defined as the `log2(# of flavors)`.
 When the number of flavors is 2, it is a `StaticBitVector`.
+
+Example
+-------------------------------
+```jldoctest; setup=:(using GraphTensorNetworks)
+julia> ev = StaticElementVector(3, [1,2,0,1,2])
+12012
+
+julia> ev[2]
+0x0000000000000002
+```
 """
 struct StaticElementVector{N,S,C}
     data::NTuple{C,UInt64}
@@ -26,6 +37,9 @@ Base.:(==)(x::StaticElementVector{N,S,C}, y::StaticElementVector{N,S,C}) where {
     end
 end
 function StaticElementVector(nflavor::Int, x::AbstractVector)
+    if any(x->x<0 || x>=nflavor, x)
+        throw(ArgumentError("Vector elements must be in range `[0, $(nflavor-1)]`, got $x."))
+    end
     N = length(x)
     S = ceil(Int,log2(nflavor)) # sometimes can not devide 64.
     convert(StaticElementVector{N,S,_nints(N,S)}, x)
@@ -69,6 +83,17 @@ end
 ##### BitVectors
 """
     StaticBitVector{N,C} = StaticElementVector{N,1,C}
+    StaticBitVector(x::AbstractVector)
+
+Example
+-------------------------------
+```jldoctest; setup=:(using GraphTensorNetworks)
+julia> sb = StaticBitVector([1,0,0,1,1])
+10011
+
+julia> sb[3]
+0x0000000000000000
+```
 """
 const StaticBitVector{N,C} = StaticElementVector{N,1,C}
 @inline function Base.getindex(x::StaticBitVector{N,C}, i::Integer) where {N,C}

src/networks/Coloring.jl

@@ -2,8 +2,8 @@
     Coloring{K,CT<:AbstractEinsum} <: GraphProblem
     Coloring{K}(graph; openvertices=(), optimizer=GreedyMethod(), simplifier=nothing)
 
-[Vertex Coloring](https://psychic-meme-f4d866f8.pages.github.io/dev/tutorials/Coloring.html) problem.
-`optimizer` and `simplifier` are for tensor network optimization, check `optimize_code` for details.
+The [Vertex Coloring](https://psychic-meme-f4d866f8.pages.github.io/dev/tutorials/Coloring.html) problem.
+`optimizer` and `simplifier` are for tensor network optimization, check [`optimize_code`](@ref) for details.
 """
 struct Coloring{K,CT<:AbstractEinsum} <: GraphProblem
     code::CT

src/networks/IndependentSet.jl

@@ -6,7 +6,7 @@
 The [independent set problem](https://psychic-meme-f4d866f8.pages.github.io/dev/tutorials/IndependentSet.html) in graph theory.
 In the constructor, `weights` are the weights of vertices.
 `openvertices` specifies labels for the output tensor.
-`optimizer` and `simplifier` are for tensor network optimization, check `optimize_code` for details.
+`optimizer` and `simplifier` are for tensor network optimization, check [`optimize_code`](@ref) for details.
 """
 struct IndependentSet{CT<:AbstractEinsum,WT<:Union{UnWeighted, Vector}} <: GraphProblem
     code::CT

src/networks/Matching.jl

@@ -2,8 +2,8 @@
     Matching{CT<:AbstractEinsum} <: GraphProblem
     Matching(graph; openvertices=(), optimizer=GreedyMethod(), simplifier=nothing)
 
-[Vertex matching](https://psychic-meme-f4d866f8.pages.github.io/dev/tutorials/Matching.html) problem.
-`optimizer` and `simplifier` are for tensor network optimization, check `optimize_code` for details.
+The [Vertex matching](https://psychic-meme-f4d866f8.pages.github.io/dev/tutorials/Matching.html) problem.
+`optimizer` and `simplifier` are for tensor network optimization, check [`optimize_code`](@ref) for details.
 """
 struct Matching{CT<:AbstractEinsum} <: GraphProblem
     symbols::Vector{Tuple{Int,Int}}