update docs

Author: GiggleLiu

docs/Project.toml

@@ -4,3 +4,4 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 GraphTensorNetworks = "0978c8c2-34f6-49c7-9826-ea2cc20dabd2"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+Polynomials = "f27b6e38-b328-58d1-80ce-0feddd5e7a45"

docs/make.jl

@@ -1,5 +1,6 @@
 using Pkg
 using GraphTensorNetworks
+using GraphTensorNetworks: TropicalNumbers, Polynomials, Mods
 using Documenter
 using DocThemeIndigo
 using Literate
@@ -18,7 +19,7 @@ indigo = DocThemeIndigo.install(GraphTensorNetworks)
 DocMeta.setdocmeta!(GraphTensorNetworks, :DocTestSetup, :(using GraphTensorNetworks); recursive=true)
 
 makedocs(;
-    modules=[GraphTensorNetworks],
+    modules=[GraphTensorNetworks, TropicalNumbers, Polynomials, Mods],
     authors="Jinguo Liu",
     repo="https://github.com/Happy-Diode/GraphTensorNetworks.jl/blob/{commit}{path}#{line}",
     sitename="GraphTensorNetworks.jl",
@@ -37,6 +38,7 @@ makedocs(;
         "Method Selection Guide" => "methodselection.md",
         "References" => "ref.md",
     ],
+    doctest=false,
 )
 
 deploydocs(;

docs/src/ref.md

@@ -1,5 +1,26 @@
+```@meta
+DocTestSetup = quote
+    import TropicalNumbers, Mods, Polynomials
+end
+```
 # References
 
 ```@autodocs
 Modules = [GraphTensorNetworks]
+```
+
+```@docs
+TropicalNumbers.Tropical
+```
+
+```@docs
+TropicalNumbers.CountingTropical
+```
+
+```@docs
+Mods.Mod
+```
+
+```@docs
+Polynomials.Polynomial
 ```

examples/IndependentSet/main.jl

@@ -1,10 +1,8 @@
 # # Independent set problem
 
 # ## Problem definition
-# An independent set is defined in the monadic second order language as
-# ```math
-# \exists x_i,\ldots,x_M\left[\bigwedge_{i\neq j} (x_i\neq x_j \wedge \neg \textbf{adj}(x_i, x_j))\right]
-# ```
+
+# Please check the docstring of [`Independence`](@ref).
 
 # ## Solving properties
 
@@ -16,25 +14,22 @@ problem = Independence(graph; optimizer=TreeSA(sc_weight=1.0, ntrials=10,
                          βs=0.01:0.1:15.0, niters=20, rw_weight=0.2));
 
 # maximum independent set size
-maximum_independent_set_size = solve(problem, "size max")
+maximum_independent_set_size = solve(problem, SizeMax())
 
 # all independent sets
-count_all_independent_sets = solve(problem, "counting sum")
-
-# counting maximum independent sets
-count_maximum_independent_sets = solve(problem, "counting max")
+count_all_independent_sets = solve(problem, CountingAll())
 
 # counting independent sets of max two sizes
-count_max2_independent_sets = solve(problem, "counting max2")
+count_max2_independent_sets = solve(problem, CountingMax(2))
 
 # compute the independence polynomial
-independence_polynomial = solve(problem, "counting all (finitefield)")
+independence_polynomial = solve(problem, GraphPolynomial(; method=:finitefield))
 
 # find one MIS
-max_config = solve(problem, "config max")
+max_config = solve(problem, SingleConfigMax(; bounded=false))
 
 # enumerate all MISs
-all_max_configs = solve(problem, "configs max (bounded)")
+all_max_configs = solve(problem, ConfigsMax(; bounded=true))
 
 # enumerate all IS configurations
-all_independent_sets = solve(problem, "configs all")
+all_independent_sets = solve(problem, ConfigsAll())

src/GraphTensorNetworks.jl

@@ -7,9 +7,39 @@ using OMEinsum
 using OMEinsum: timespace_complexity, getixsv
 using Graphs
 
+# OMEinsum
 export timespace_complexity, @ein_str
 export GreedyMethod, TreeSA, SABipartite, KaHyParBipartite, MergeVectors, MergeGreedy
 
+# Algebras
+export StaticBitVector, StaticElementVector, @bv_str
+export is_commutative_semiring
+export Max2Poly, TruncatedPoly, Polynomial, Tropical, CountingTropical, StaticElementVector, Mod, ConfigEnumerator, onehotv, ConfigSampler
+
+# Lower level APIs
+export AllConfigs, SingleConfig
+export best_solutions, best2_solutions, solutions, all_solutions
+export bestk_solutions
+export contractx, contractf, graph_polynomial, max_size, max_size_count
+
+# Graphs
+export random_regular_graph, diagonal_coupled_graph, isindependentset
+export square_lattice_graph, unitdisk_graph
+
+# Tensor Networks (Graph problems)
+export Independence, MaximalIndependence, Matching, Coloring, optimize_code, set_packing, MaxCut, PaintShop, paintshop_from_pairs, UnWeighted
+
+# Interfaces
+export solve, SizeMax, CountingAll, CountingMax, GraphPolynomial, SingleConfigMax, ConfigsAll, ConfigsMax
+
+# Utilities
+export is_independent_set
+export mis_compactify!
+export save_configs, load_configs
+
+# Visualization
+export vizeinsum, vizconfig
+
 project_relative_path(xs...) = normpath(joinpath(dirname(dirname(pathof(@__MODULE__))), xs...))
 
 include("utils.jl")

src/arithematics.jl

@@ -1,7 +1,3 @@
-export is_commutative_semiring
-export Max2Poly, TruncatedPoly, Polynomial, Tropical, CountingTropical, StaticElementVector, Mod, ConfigEnumerator, onehotv, ConfigSampler
-export set_type, sampler_type
-
 using Polynomials: Polynomial
 using TropicalNumbers: Tropical, CountingTropical
 using Mods, Primes
@@ -60,7 +56,16 @@ function is_commutative_semiring(a::T, b::T, c::T) where T
     return true
 end
 
-# get maximum two countings (polynomial truncated to largest two orders)
+"""
+    TruncatedPoly{K,T,TO} <: Number
+
+Polynomial truncated to largest `K` orders. `T` is the coefficients type and `TO` is the orders type.
+
+```jldoctest; setup=(using GraphTensorNetworks)
+julia> TruncatedPoly((1,2,3), 6)
+x^4 + 2*x^5 + 3*x^6
+```
+"""
 struct TruncatedPoly{K,T,TO} <: Number
     coeffs::NTuple{K,T}
     maxorder::TO
@@ -125,6 +130,24 @@ end
 Base.:*(a::Bool, y::TruncatedPoly{K,T,TO}) where {K,T,TO} = a ? y : zero(y)
 Base.:*(y::TruncatedPoly{K,T,TO}, a::Bool) where {K,T,TO} = a ? y : zero(y)
 
+"""
+    ConfigEnumerator{N,S,C}
+
+Set algebra for enumerating configurations, 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)
+julia> a = ConfigEnumerator([StaticBitVector([1,1,1,0,0]), StaticBitVector([1,0,0,0,1])])
+{11100, 10001}
+
+julia> b = ConfigEnumerator([StaticBitVector([0,0,0,0,0]), StaticBitVector([1,0,1,0,1])])
+{00000, 10101}
+
+julia> a + b
+{11100, 10001, 00000, 10101}
+```
+"""
 struct ConfigEnumerator{N,S,C}
     data::Vector{StaticElementVector{N,S,C}}
 end
@@ -158,6 +181,18 @@ Base.show(io::IO, x::ConfigEnumerator) = print(io, "{", join(x.data, ", "), "}")
 Base.show(io::IO, ::MIME"text/plain", x::ConfigEnumerator) = Base.show(io, x)
 
 # the algebra sampling one of the configurations
+"""
+    ConfigSampler{N,S,C}
+
+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)
+julia> ConfigSampler(StaticBitVector([1,1,1,0,0]))
+ConfigSampler{5, 1, 1}(11100)
+```
+"""
 struct ConfigSampler{N,S,C}
     data::StaticElementVector{N,S,C}
 end

src/bitvector.jl

@@ -1,5 +1,3 @@
-export StaticBitVector, StaticElementVector, @bv_str
-
 """
     StaticElementVector{N,S,C}
 

src/bounding.jl

@@ -1,7 +1,5 @@
 using OMEinsum: DynamicEinCode
 
-export AllConfigs, SingleConfig
-
 struct AllConfigs{K} end
 largest_k(::AllConfigs{K}) where K = K
 struct SingleConfig end

src/configurations.jl

@@ -1,6 +1,3 @@
-export best_solutions, best2_solutions, solutions, all_solutions
-export bestk_solutions
-
 """
     best_solutions(problem; all=false, usecuda=false)
     

src/graph_polynomials.jl

@@ -3,8 +3,6 @@ using OMEinsum: NestedEinsum, getixs, getiy
 using FFTW
 using Graphs
 
-export contractx, contractf, graph_polynomial, max_size, max_size_count
-
 """
     graph_polynomial(problem, method; usecuda=false, kwargs...)