fix documents

GiggleLiu · GiggleLiu · commit 460a30d9829c · 2024-12-08T15:41:29.000+08:00
diff --git a/NEWS.md b/NEWS.md
@@ -4,4 +4,5 @@
 2. Rename `best_solutions` to `largest_solutions`, `best2_solutions` to `largest2_solutions` and `bestk_solutions` to `largestk_solutions`.
 3. Remove the weights from `PaintShop`.
 4. Remove the weights on vertices from `MaxCut`.
-5. `SpinGlass` is no longer specified by cliques. It is now specified by graphs or hypergraphs. Weights can be defined on both edges and vertices.
+5. `SpinGlass` is no longer specified by cliques. It is now specified by graphs or hypergraphs. Weights can be defined on both edges and vertices.
+6. Remove `unit_disk_graph`, replace it with `UnitDiskGraph` from `ProblemReductions`.
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,6 +1,6 @@
 using Pkg
 using GenericTensorNetworks
-using GenericTensorNetworks: TropicalNumbers, Polynomials, OMEinsum, OMEinsum.OMEinsumContractionOrders, LuxorGraphPlot
+using GenericTensorNetworks: TropicalNumbers, Polynomials, OMEinsum, OMEinsum.OMEinsumContractionOrders, LuxorGraphPlot, ProblemReductions
 using Documenter
 using DocThemeIndigo
 using Literate
@@ -17,7 +17,7 @@ indigo = DocThemeIndigo.install(GenericTensorNetworks)
 DocMeta.setdocmeta!(GenericTensorNetworks, :DocTestSetup, :(using GenericTensorNetworks); recursive=true)
 
 makedocs(;
-    modules=[GenericTensorNetworks, TropicalNumbers, OMEinsum, OMEinsumContractionOrders, LuxorGraphPlot],
+    modules=[GenericTensorNetworks, ProblemReductions, TropicalNumbers, OMEinsum, OMEinsumContractionOrders, LuxorGraphPlot],
     authors="Jinguo Liu",
     repo="https://github.com/QuEraComputing/GenericTensorNetworks.jl/blob/{commit}{path}#{line}",
     sitename="GenericTensorNetworks.jl",
@@ -40,7 +40,6 @@ makedocs(;
             "Satisfiability problem" => "generated/Satisfiability.md",
             "Set covering problem" => "generated/SetCovering.md",
             "Set packing problem" => "generated/SetPacking.md",
-            #"Other problems" => "generated/Others.md",
         ],
         "Topics" => [
             "Gist" => "gist.md",
diff --git a/docs/src/ref.md b/docs/src/ref.md
@@ -15,28 +15,33 @@ PaintShop
 Satisfiability
 SetCovering
 SetPacking
-OpenPitMining
 ```
 
 #### Constraint Satisfaction Problem Interfaces
 
 To subtype [`ConstraintSatisfactionProblem`](@ref), a new type must contain a `code` field to represent the (optimized) tensor network.
-Interfaces [`GenericTensorNetworks.generate_tensors`](@ref), [`labels`](@ref), [`flavors`](@ref) and [`weights`](@ref) are required.
+Interfaces [`GenericTensorNetworks.generate_tensors`](@ref), [`flavors`](@ref) and [`weights`](@ref) are required.
 [`num_flavors`](@ref) is optional.
 
 ```@docs
 GenericTensorNetworks.generate_tensors
-labels
-energy_terms
 flavors
 weights
 set_weights
+is_weighted
 num_flavors
 fixedvertices
 ```
 
 #### Constraint Satisfaction Problem Utilities
 ```@docs
+hard_constraints
+is_satisfied
+local_solution_spec
+solution_size
+energy_mode
+energy
+
 is_independent_set
 is_maximal_independent_set
 is_dominating_set
@@ -46,10 +51,7 @@ is_set_covering
 is_set_packing
 
 cut_size
-spinglass_energy
 num_paint_shop_color_switch
-paint_shop_coloring_from_config
-mis_compactify!
 
 CNF
 CNFClause
@@ -60,8 +62,7 @@ satisfiable
 ¬
 ∧
 
-is_valid_mining
-print_mining
+mis_compactify!
 ```
 
 ## Properties
@@ -145,7 +146,12 @@ MergeGreedy
 
 ## Others
 #### Graph
+Except the `SimpleGraph` defined in [Graphs](https://github.com/JuliaGraphs/Graphs.jl), `GenericTensorNetworks` also defines the following types and functions.
+
 ```@docs
+HyperGraph
+UnitDiskGraph
+
 show_graph
 show_configs
 show_einsum
@@ -162,7 +168,6 @@ render_locs
 
 diagonal_coupled_graph
 square_lattice_graph
-unit_disk_graph
 line_graph
 
 random_diagonal_coupled_graph
diff --git a/docs/src/tensornetwork.md b/docs/src/tensornetwork.md
@@ -51,7 +51,6 @@ The maximum/minimum solution sizes can be represented as a tensor network as wel
 which can be represented as a tropical tensor network[^Liu2021] $(V, \{h_{\sigma_e} \mid e\in E\}, \emptyset)$, where $h_{\sigma_e}$ is a tensor labeled by $\sigma_e \subseteq V$, and its elements are defined by $h_{\sigma_e}= h_e(\sigma_e)$.
 
 ## Problems
-### Independent set problem
 The independent set problem on graph $G=(V, E)$ is characterized by the Hamiltonian
 ```math
 H(\sigma) = U \sum_{(i, j) \in E}  n_i n_j - \sum_{i \in V} n_i
diff --git a/examples/Coloring.jl b/examples/Coloring.jl
@@ -46,10 +46,11 @@ problem = GenericTensorNetwork(coloring)
 
 # ## Solving properties
 # ##### counting all possible coloring
-num_of_coloring = solve(problem, CountingMax())[]
+# The size of a coloring problem is the number of violations of the coloring constraint.
+num_of_coloring = solve(problem, CountingMin())[]
 
 # ##### finding one best coloring
-single_solution = solve(problem, SingleConfigMax())[]
+single_solution = solve(problem, SingleConfigMin())[]
 read_config(single_solution)
 
 is_vertex_coloring(graph, read_config(single_solution))
@@ -68,7 +69,7 @@ show_graph(linegraph, [(locations[e.src] .+ locations[e.dst])
 # Let us construct the tensor network and see if there are solutions.
 lineproblem = Coloring{3}(linegraph);
 
-num_of_coloring = solve(GenericTensorNetwork(lineproblem), CountingMax())[]
+num_of_coloring = solve(GenericTensorNetwork(lineproblem), CountingMin())[]
 read_size_count(num_of_coloring)
 
 # You will see the maximum size 28 is smaller than the number of edges in the `linegraph`,
diff --git a/examples/PaintShop.jl b/examples/PaintShop.jl
@@ -12,7 +12,7 @@
 # In the following, we use a character to represent a car,
 # and defined a binary paint shop problem as a string that each character appear exactly twice.
 
-using GenericTensorNetworks, Graphs
+using GenericTensorNetworks, Graphs, GenericTensorNetworks.ProblemReductions
 
 sequence = collect("iadgbeadfcchghebif")
 
@@ -88,7 +88,7 @@ best_configs = solve(problem, ConfigsMin())[]
 
 # One can see to identical bitstrings corresponding two different vertex configurations, they are related to bit-flip symmetry.
 
-painting1 = paint_shop_coloring_from_config(pshop, read_config(best_configs)[1])
+painting1 = ProblemReductions.paint_shop_coloring_from_config(pshop, read_config(best_configs)[1])
 
 show_graph(graph, locations; format=:svg, texts=string.(sequence),
     edge_colors=[sequence[e.src] == sequence[e.dst] ? "blue" : "black" for e in edges(graph)],
diff --git a/examples/Satisfiability.jl b/examples/Satisfiability.jl
@@ -8,7 +8,7 @@
 # One can specify a satisfiable problem in the [conjunctive normal form](https://en.wikipedia.org/wiki/Conjunctive_normal_form).
 # In boolean logic, a formula is in conjunctive normal form (CNF) if it is a conjunction (∧) of one or more clauses,
 # where a clause is a disjunction (∨) of literals.
-using GenericTensorNetworks
+using GenericTensorNetworks, GenericTensorNetworks.ProblemReductions
 
 @bools a b c d e f g
 
@@ -48,15 +48,15 @@ problem = GenericTensorNetwork(sat)
 
 # ## Solving properties
 # #### Satisfiability and its counting
-# The size of a satisfiability problem is defined by the number of satisfiable clauses.
-num_satisfiable = solve(problem, SizeMax())[]
+# The size of a satisfiability problem is defined by the number of unsatisfied clauses.
+num_satisfiable = solve(problem, SizeMin())[]
 
 # The [`GraphPolynomial`](@ref) of a satisfiability problem counts the number of solutions that `k` clauses satisfied.
 num_satisfiable_count = read_size_count(solve(problem, GraphPolynomial())[])
 
 # #### Find one of the solutions
-single_config = read_config(solve(problem, SingleConfigMax())[])
+single_config = read_config(solve(problem, SingleConfigMin())[])
 
 # One will see a bit vector printed.
 # One can create an assignment and check the validity with the following statement:
-satisfiable(cnf, Dict(zip(labels(problem), single_config)))
+satisfiable(cnf, Dict(zip(ProblemReductions.symbols(problem.problem), single_config)))
diff --git a/examples/SetCovering.jl b/examples/SetCovering.jl
@@ -73,7 +73,7 @@ min_configs = read_config(solve(problem, ConfigsMin())[])
 # Hence the two optimal solutions are ``\{z_1, z_3, z_5, z_6\}`` and ``\{z_2, z_3, z_4, z_5\}``.
 # The correctness of this result can be checked with the [`is_set_covering`](@ref) function.
 
-all(c->is_set_covering(sets, c), min_configs)
+all(c->is_set_covering(problem.problem, c), min_configs)
 
 # Similarly, if one is only interested in computing one of the minimum set coverings,
 # one can use the graph property [`SingleConfigMin`](@ref).
diff --git a/examples/SetPacking.jl b/examples/SetPacking.jl
@@ -74,7 +74,7 @@ max_configs = read_config(solve(problem, ConfigsMax())[])
 # Hence the only optimal solution is ``\{z_1, z_3, z_6\}`` that has size 3.
 # The correctness of this result can be checked with the [`is_set_packing`](@ref) function.
 
-all(c->is_set_packing(sets, c), max_configs)
+all(c->is_set_packing(problem.problem, c), max_configs)
 
 # Similarly, if one is only interested in computing one of the maximum set packing,
 # one can use the graph property [`SingleConfigMax`](@ref).
diff --git a/examples/SpinGlass.jl b/examples/SpinGlass.jl
@@ -26,7 +26,7 @@ show_graph(graph, locations; format=:svg)
 
 # ## Generic tensor network representation
 # An anti-ferromagnetic spin glass problem can be defined with the [`SpinGlass`](@ref) type as
-spinglass = SpinGlass(graph, fill(1, ne(graph)))
+spinglass = SpinGlass(graph, fill(1, ne(graph)), zeros(Int, nv(graph)))
 
 # The tensor network representation of the set packing problem can be obtained by
 problem = GenericTensorNetwork(spinglass)
@@ -81,8 +81,10 @@ partition_function = solve(problem, GraphPolynomial())[]
 #  The ground state of the spin glass problem can be found by the [`SingleConfigMin`](@ref) solver.
 ground_state = read_config(solve(problem, SingleConfigMin())[])
 
-# The energy of the ground state can be verified by the [`spinglass_energy`](@ref) function.
-Emin_verify = spinglass_energy(spinglass, ground_state)
+# The energy of the ground state can be verified by the [`energy`](@ref) function.
+# Note the output of the ground state can not be directly used as the input of the `energy` function.
+# It needs to be converted to the spin configurations.
+Emin_verify = energy(problem.problem, 1 .- 2 .* Int.(ground_state))
 
 # You should see a consistent result as above `Emin`.
 
@@ -117,7 +119,7 @@ weights = [-1, 1, -1, 1, -1, 1, -1, 1];
 # \end{align*}
 # ```
 # A spin glass problem can be defined with the [`SpinGlass`](@ref) type as
-hyperspinglass = SpinGlass(num_vertices, hyperedges, weights)
+hyperspinglass = SpinGlass(HyperGraph(num_vertices, hyperedges), weights, zeros(Int, num_vertices))
 
 # The tensor network representation of the set packing problem can be obtained by
 hyperproblem = GenericTensorNetwork(hyperspinglass)
@@ -155,8 +157,8 @@ poly = solve(hyperproblem, GraphPolynomial())[]
 # The ground state of the spin glass problem can be found by the [`SingleConfigMin`](@ref) solver.
 ground_state = read_config(solve(hyperproblem, SingleConfigMin())[])
 
-# The energy of the ground state can be verified by the [`spinglass_energy`](@ref) function.
+# The energy of the ground state can be verified by the [`energy`](@ref) function.
 
-Emin_verify = spinglass_energy(hyperspinglass, ground_state)
+Emin_verify = energy(hyperproblem.problem, 1 .- 2 .* Int.(ground_state))
 
 # You should see a consistent result as above `Emin`.
diff --git a/examples/weighted.jl b/examples/weighted.jl
@@ -1,7 +1,7 @@
 # # Weighted problems
 # Let us use the maximum independent set problem on Petersen graph as an example.
 
-using GenericTensorNetworks, Graphs
+using GenericTensorNetworks, GenericTensorNetworks.ProblemReductions, Graphs
 
 graph = Graphs.smallgraph(:petersen)
 
@@ -10,7 +10,7 @@ problem = GenericTensorNetwork(IndependentSet(graph, collect(1:10)));
 GenericTensorNetworks.weights(problem)
 
 # The tensor labels that associated with the weights can be accessed by
-GenericTensorNetworks.energy_terms(problem)
+ProblemReductions.local_solution_spec(problem.problem)
 
 # Here, the `weights` keyword argument can be a vector for weighted graphs or `UnitWeight()` for unweighted graphs.
 # Most solution space properties work for unweighted graphs also work for the weighted graphs.
diff --git a/src/GenericTensorNetworks.jl b/src/GenericTensorNetworks.jl
@@ -16,11 +16,11 @@ using Primes
 using DocStringExtensions
 using Base.Cartesian
 using ProblemReductions
-import ProblemReductions: ConstraintSatisfactionProblem, AbstractSatisfiabilityProblem, UnitWeight
+import ProblemReductions: ConstraintSatisfactionProblem, AbstractSatisfiabilityProblem, UnitWeight, hard_constraints, is_satisfied, local_solution_spec, solution_size, energy_mode, LargerSizeIsBetter, SmallerSizeIsBetter
 import ProblemReductions: @bv_str, StaticElementVector, StaticBitVector, onehotv, _nints, hamming_distance
 import ProblemReductions: is_set_covering, is_vertex_coloring, is_set_packing, is_dominating_set, is_matching, is_maximal_independent_set, cut_size, is_independent_set
 import ProblemReductions: num_paint_shop_color_switch, spin_glass_from_matrix, CNF, CNFClause, BoolVar, satisfiable, @bools, ∨, ¬, ∧
-import ProblemReductions: flavors, set_weights, weights, num_flavors, variables
+import ProblemReductions: flavors, set_weights, weights, is_weighted, num_flavors, variables, energy
 import AbstractTrees: children, printnode, print_tree
 import StatsBase
 
@@ -40,18 +40,23 @@ export CountingTropicalF64, CountingTropicalF32, TropicalF64, TropicalF32, Exten
 export generate_samples, OnehotVec
 
 # Graphs
+export HyperGraph, SimpleGraph, UnitDiskGraph
 export random_regular_graph, diagonal_coupled_graph
-export square_lattice_graph, unit_disk_graph, random_diagonal_coupled_graph, random_square_lattice_graph
+export square_lattice_graph, random_diagonal_coupled_graph, random_square_lattice_graph
 export line_graph
 
+
+# Problems
+export AbstractProblem, ConstraintSatisfactionProblem
+export hard_constraints, is_satisfied, local_solution_spec, solution_size, energy_mode, LargerSizeIsBetter, SmallerSizeIsBetter
 # Tensor Networks (Graph problems)
 export GenericTensorNetwork, optimize_code, UnitWeight
-export flavors, variables, num_flavors, weights, fixedvertices, set_weights, energy_terms
+export flavors, variables, num_flavors, weights, fixedvertices, set_weights, is_weighted
 export IndependentSet, mis_compactify!, is_independent_set
 export MaximalIS, is_maximal_independent_set
 export cut_size, MaxCut
-export spinglass_energy, spin_glass_from_matrix, SpinGlass
-export PaintShop, paintshop_from_pairs, num_paint_shop_color_switch, paint_shop_coloring_from_config, paint_shop_from_pairs
+export energy, spin_glass_from_matrix, SpinGlass
+export PaintShop, paintshop_from_pairs, num_paint_shop_color_switch
 export Coloring, is_vertex_coloring
 export Satisfiability, CNF, CNFClause, BoolVar, satisfiable, @bools, ∨, ¬, ∧
 export DominatingSet, is_dominating_set
diff --git a/src/graphs.jl b/src/graphs.jl
@@ -15,7 +15,7 @@ Create a masked square lattice graph.
 """
 function square_lattice_graph(mask::AbstractMatrix{Bool})
     locs = [(i, j) for i=1:size(mask, 1), j=1:size(mask, 2) if mask[i,j]]
-    unit_disk_graph(locs, 1.1)
+    UnitDiskGraph(locs, 1.1)
 end
 
 """
@@ -41,23 +41,7 @@ Create a masked diagonal coupled square lattice graph from a specified `mask`.
 """
 function diagonal_coupled_graph(mask::AbstractMatrix{Bool})
     locs = [(i, j) for i=1:size(mask, 1), j=1:size(mask, 2) if mask[i,j]]
-    unit_disk_graph(locs, 1.5)
-end
-
-"""
-    unit_disk_graph(locs::AbstractVector, unit::Real)
-
-Create a unit disk graph with locations specified by `locs` and unit distance `unit`.
-"""
-function unit_disk_graph(locs::AbstractVector, unit::Real)
-    n = length(locs)
-    g = SimpleGraph(n)
-    for i=1:n, j=i+1:n
-        if sum(abs2, locs[i] .- locs[j]) < unit ^ 2
-            add_edge!(g, i, j)
-        end
-    end
-    return g
+    UnitDiskGraph(locs, 1.5)
 end
 
 """
diff --git a/src/interfaces.jl b/src/interfaces.jl
@@ -275,16 +275,15 @@ function solve(gp::GenericTensorNetwork, property::AbstractProperty; T=Float64,
         res = contractx(gp, pre_invert_exponent(TruncatedPoly(ntuple(i->i == min_k(property) ? one(T) : zero(T), min_k(property)), one(T))); usecuda=usecuda)
         return asarray(post_invert_exponent.(res), res)
     elseif property isa GraphPolynomial
-        ws = weights(gp)
-        if !(eltype(ws) <: Integer)
+        # fix the fake non-integer weights
+        if is_weighted(gp) && !(eltype(weights(gp)) <: Integer)
             @warn "Input weights are not Integer types, try casting to weights of `Int64` type..."
-            gp = set_weights(gp, Int.(ws))
-            ws = weights(gp)
+            gp = set_weights(gp, Int.(weights(gp)))
         end
-        if size_all_positive(gp.problem)
+        if !is_weighted(gp) || size_all_positive(gp.problem)
             return graph_polynomial(gp, Val(graph_polynomial_method(property)); usecuda=usecuda, T=T, property.kwargs...)
-        elseif size_all_negative(gp.problem)
-            res = graph_polynomial(set_weights(gp, -ws), Val(graph_polynomial_method(property)); usecuda=usecuda, T=T, property.kwargs...)
+        elseif is_weighted(gp) && size_all_negative(gp.problem)
+            res = graph_polynomial(set_weights(gp, -weights(gp)), Val(graph_polynomial_method(property)); usecuda=usecuda, T=T, property.kwargs...)
             return asarray(invert_polynomial.(res), res)
         else
             if graph_polynomial_method(property) != :laurent
diff --git a/src/networks.jl b/src/networks.jl
@@ -50,6 +50,7 @@ end
 variables(gp::GenericTensorNetwork) = variables(gp.problem)
 set_weights(gp::GenericTensorNetwork, weights) = GenericTensorNetwork(set_weights(gp.problem, weights), gp.code, gp.fixedvertices)
 weights(gp::GenericTensorNetwork) = weights(gp.problem)
+is_weighted(gp::GenericTensorNetwork) = is_weighted(gp.problem)
 
 """
     fixedvertices(tnet::GenericTensorNetwork) -> Dict
diff --git a/test/graphs.jl b/test/graphs.jl
@@ -5,7 +5,7 @@ using GenericTensorNetworks, Test, Graphs
     @test nv(g) == 50
     g = random_diagonal_coupled_graph(10, 10, 0.5)
     @test nv(g) == 50
-    g = unit_disk_graph([(0.1, 0.2), (0.2, 0.3), (1.2, 1.4)], 1.0)
+    g = UnitDiskGraph([(0.1, 0.2), (0.2, 0.3), (1.2, 1.4)], 1.0)
     @test ne(g) == 1
     @test nv(g) == 3
 end
