resolve pr comments

Author: GiggleLiu

benchmark/bench_map.jl

@@ -6,11 +6,10 @@ using Artifacts
 
 const SUITE = BenchmarkGroup()
 
-model_filepath, evidence_filepath, _, solution_filepath = get_instance_filepaths("Promedus_14", "MAR")
-problem = read_instance(model_filepath; evidence_filepath, solution_filepath)
+problem = problem_from_artifact("uai2014", "MAR" "Promedus", 14)
 
 optimizer = TreeSA(ntrials = 1, niters = 2, βs = 1:0.1:40)
-tn = TensorNetworkModel(problem; optimizer)
+tn = TensorNetworkModel(read_model(problem); optimizer, evidence=get_evidence(problem))
 SUITE["map"] = @benchmarkable most_probable_config(tn)
 
 end  # module

benchmark/bench_mar.jl

@@ -8,8 +8,8 @@ using Artifacts
 
 const SUITE = BenchmarkGroup()
 
-model_filepath, evidence_filepath, _, solution_filepath = get_instance_filepaths("Promedus_14", "MAR")
-problem = read_instance(model_filepath; evidence_filepath, solution_filepath)
+model_filepath, evidence_filepath, _, solution_filepath = get_model_filepaths("Promedus_14", "MAR")
+problem = read_model(model_filepath; evidence_filepath, solution_filepath)
 
 optimizer = TreeSA(ntrials = 1, niters = 5, βs = 0.1:0.1:100)
 tn1 = TensorNetworkModel(problem; optimizer)

benchmark/bench_mmap.jl

@@ -6,8 +6,8 @@ using Artifacts
 
 const SUITE = BenchmarkGroup()
 
-model_filepath, evidence_filepath, _, solution_filepath = get_instance_filepaths("Promedus_14", "MAR")
-problem = read_instance(model_filepath; evidence_filepath, solution_filepath)
+model_filepath, evidence_filepath, _, solution_filepath = get_model_filepaths("Promedus_14", "MAR")
+problem = read_model(model_filepath; evidence_filepath, solution_filepath)
 optimizer = TreeSA(ntrials = 1, niters = 2, βs = 1:0.1:40)
 
 # Does not marginalize any var

docs/src/api/public.md

@@ -42,7 +42,7 @@ MMAPModel
 RescaledArray
 TensorNetworkModel
 ArtifactProblemSpec
-UAIInstance
+UAIModel
 ```
 
 ## Functions
@@ -58,13 +58,12 @@ most_probable_config
 probability
 dataset_from_artifact
 problem_from_artifact
-read_instance
+read_model
 read_evidence
 read_solution
 read_queryvars
-read_instance_file
+read_model_file
 read_evidence_file
-read_solution_file
 read_td_file
 sample
 ```

docs/src/performance.md

@@ -1,27 +1,16 @@
 # Performance Tips
 ## Optimize contraction orders
 
-Let us use the independent set problem on 3-regular graphs as an example.
-```julia
-julia> using TensorInference, Artifacts, Pkg
-
-julia> Pkg.ensure_artifact_installed("uai2014", pkgdir(TensorInference, "test", "Artifacts.toml"));
-
-julia> function get_instance_filepaths(problem_name::AbstractString, task::AbstractString)
-        model_filepath = joinpath(artifact"uai2014", task, problem_name * ".uai")
-        evidence_filepath = joinpath(artifact"uai2014", task, problem_name * ".uai.evid")
-        solution_filepath = joinpath(artifact"uai2014", task, problem_name * ".uai." * task)
-        return model_filepath, evidence_filepath, solution_filepath
-    end
-
-julia> model_filepath, evidence_filepath, solution_filepath = get_instance_filepaths("Promedus_14", "MAR")
-
-julia> instance = read_instance(model_filepath; evidence_filepath, solution_filepath)
+Let us use a problem instance from the "Promedus" dataset of the UAI 2014 competition as an example.
+```@repl performance
+using TensorInference
+problem = problem_from_artifact("uai2014", "MAR", "Promedus", 11)
+model, evidence = read_model(problem), read_evidence(problem);
 ```
 
 Next, we select the tensor network contraction order optimizer.
-```julia
-julia> optimizer = TreeSA(ntrials = 1, niters = 5, βs = 0.1:0.1:100)
+```@repl performance
+optimizer = TreeSA(ntrials = 1, niters = 5, βs = 0.1:0.3:100)
 ```
 
 Here, we choose the local search based [`TreeSA`](@ref) algorithm, which often finds the smallest time/space complexity and supports slicing.
@@ -32,41 +21,32 @@ Alternative tensor network contraction order optimizers include
 * [`KaHyParBipartite`](@ref)
 * [`SABipartite`](@ref)
 
-```julia
-julia> tn = TensorNetworkModel(instance; optimizer)
+```@repl performance
+tn = TensorNetworkModel(model; optimizer, evidence);
 ```
 The returned object `tn` contains a field `code` that specifies the tensor network with optimized contraction order. To check the contraction complexity, please type
-```julia
-julia> contraction_complexity(problem)
+```@repl performance
+contraction_complexity(tn)
 ```
 
 The returned object contains log2 values of the number of multiplications, the number elements in the largest tensor during contraction and the number of read-write operations to tensor elements.
 
-```julia
-julia> p1 = probability(tn)
+```@repl performance
+probability(tn)
 ```
 
 ## Slicing technique
 
 For large scale applications, it is also possible to slice over certain degrees of freedom to reduce the space complexity, i.e.
 loop and accumulate over certain degrees of freedom so that one can have a smaller tensor network inside the loop due to the removal of these degrees of freedom.
 In the [`TreeSA`](@ref) optimizer, one can set `nslices` to a value larger than zero to turn on this feature.
-
-```julia
-julia> tn = TensorNetworkModel(instance; optimizer=TreeSA());
-
-julia> contraction_complexity(tn)
-(20.856518235241687, 16.0, 18.88208476145812)
-```
-
-As a comparision we slice over 5 degrees of freedom, which can reduce the space complexity by at most 5.
+As a comparison we slice over 5 degrees of freedom, which can reduce the space complexity by at most 5.
 In this application, the slicing achieves the largest possible space complexity reduction 5, while the time and read-write complexity are only increased by less than 1,
 i.e. the peak memory usage is reduced by a factor ``32``, while the (theoretical) computing time is increased by at a factor ``< 2``.
-```
-julia> tn = TensorNetworkModel(instance; optimizer=TreeSA(nslices=5));
-
-julia> timespacereadwrite_complexity(problem)
-(21.134967710592804, 11.0, 19.84529401927876)
+```@repl performance
+optimizer = TreeSA(ntrials = 1, niters = 5, βs = 0.1:0.3:100, nslices=5)
+tn = TensorNetworkModel(model; optimizer, evidence);
+contraction_complexity(problem)
 ```
 
 ## GEMM for Tropical numbers
@@ -80,7 +60,7 @@ To upload the computation to GPU, you just add `using CUDA` before calling the `
 julia> using CUDA
 [ Info: OMEinsum loaded the CUDA module successfully
 
-julia> marginals(tn; usecuda = true)
+julia> marginals(tn; usecuda = true);
 ```
 
 Functions support `usecuda` keyword argument includes

examples/asia/main.jl

@@ -51,12 +51,12 @@ using TensorInference
 # Load the ASIA network model from the `asia.uai` file located in the examples
 # directory. See [Model file format (.uai)](@ref) for a description of the
 # format of this file.
-instance = read_instance_file(pkgdir(TensorInference, "examples", "asia", "asia.uai"))
+model = read_model_file(pkgdir(TensorInference, "examples", "asia", "asia.uai"))
 
 # ---
 
 # Create a tensor network representation of the loaded model.
-tn = TensorNetworkModel(instance)
+tn = TensorNetworkModel(model)
 
 # ---
 
@@ -78,7 +78,7 @@ get_vars(tn)
 # Set an evidence: Assume that the "X-ray" result (variable 7) is positive.
 # Since setting an evidence may affect the contraction order of the tensor
 # network, recompute it.
-tn = TensorNetworkModel(instance, evidence = Dict(7 => 0))
+tn = TensorNetworkModel(model, evidence = Dict(7 => 0))
 
 # ---
 
@@ -103,7 +103,7 @@ logp, cfg = most_probable_config(tn)
 # Compute the most probable values of certain variables (e.g., 4 and 7) while
 # marginalizing over others. This is known as Maximum a Posteriori (MAP)
 # estimation.
-mmap = MMAPModel(instance, evidence=Dict(7=>0), queryvars=[4,7])
+mmap = MMAPModel(model, evidence=Dict(7=>0), queryvars=[4,7])
 
 # ---
 

src/Core.jl

@@ -23,16 +23,16 @@ $(TYPEDEF)
 * `cards` is a vector of cardinalities for variables,
 * `factors` is a vector of factors,
 """
-struct UAIInstance{ET, FT <: Factor{ET}}
+struct UAIModel{ET, FT <: Factor{ET}}
     nvars::Int
     nclique::Int
     cards::Vector{Int}
     factors::Vector{FT}
 end
 
-Base.show(io::IO, ::MIME"text/plain", uai::UAIInstance) = Base.show(io, uai)
-function Base.show(io::IO, uai::UAIInstance)
-    println(io, "UAIInstance(nvars = $(uai.nvars), nclique = $(uai.nclique))")
+Base.show(io::IO, ::MIME"text/plain", uai::UAIModel) = Base.show(io, uai)
+function Base.show(io::IO, uai::UAIModel)
+    println(io, "UAIModel(nvars = $(uai.nvars), nclique = $(uai.nclique))")
     println(io, " variables :")
     println(io, " factors : ")
     for (k, f) in enumerate(uai.factors)
@@ -89,16 +89,16 @@ end
 $(TYPEDSIGNATURES)
 """
 function TensorNetworkModel(
-    instance::UAIInstance;
+    model::UAIModel;
     openvars = (),
     evidence = Dict{Int,Int}(),
     optimizer = GreedyMethod(),
     simplifier = nothing
 )::TensorNetworkModel
     return TensorNetworkModel(
-        1:(instance.nvars),
-        instance.cards,
-        instance.factors;
+        1:(model.nvars),
+        model.cards,
+        model.factors;
         openvars,
         evidence,
         optimizer,

src/TensorInference.jl

@@ -18,9 +18,9 @@ export RescaledArray
 export contraction_complexity, TreeSA, GreedyMethod, KaHyParBipartite, SABipartite, MergeGreedy, MergeVectors
 
 # read and load uai files
-export read_instance_file, read_td_file, read_evidence_file, read_solution_file
+export read_model_file, read_td_file, read_evidence_file
 export problem_from_artifact, ArtifactProblemSpec
-export read_instance, UAIInstance, read_evidence, read_solution, read_queryvars, dataset_from_artifact
+export read_model, UAIModel, read_evidence, read_solution, read_queryvars, dataset_from_artifact
 
 # marginals
 export TensorNetworkModel, get_vars, get_cards, log_probability, probability, marginals

src/mmap.jl

@@ -58,9 +58,9 @@ end
 """
 $(TYPEDSIGNATURES)
 """
-function MMAPModel(instance::UAIInstance; openvars = (), optimizer = GreedyMethod(), queryvars, evidence = Dict{Int, Int}(), simplifier = nothing)::MMAPModel
+function MMAPModel(model::UAIModel; openvars = (), optimizer = GreedyMethod(), queryvars, evidence = Dict{Int, Int}(), simplifier = nothing)::MMAPModel
     return MMAPModel(
-        1:(instance.nvars), instance.cards, instance.factors; queryvars, evidence, optimizer, simplifier, openvars
+        1:(model.nvars), model.cards, model.factors; queryvars, evidence, optimizer, simplifier, openvars
     )
 end
 

src/utils.jl

@@ -1,21 +1,21 @@
 """
 $(TYPEDSIGNATURES)
 
-Parse the problem instance found in `instance_filepath` defined in the UAI instance
+Parse the problem instance found in `model_filepath` defined in the UAI model
 format. If the provided file path is empty, return `nothing`.
 
 The UAI file formats are defined in:
 https://uaicompetition.github.io/uci-2022/file-formats/
 """
-function read_instance_file(instance_filepath::AbstractString; factor_eltype = Float64)::UAIInstance
+function read_model_file(model_filepath::AbstractString; factor_eltype = Float64)::UAIModel
     # Read the uai file into an array of lines
-    str = open(instance_filepath) do file
+    str = open(model_filepath) do file
         read(file, String)
     end
-    return read_instance_from_string(str; factor_eltype)
+    return read_model_from_string(str; factor_eltype)
 end
 
-function read_instance_from_string(str::AbstractString; factor_eltype = Float64)::UAIInstance
+function read_model_from_string(str::AbstractString; factor_eltype = Float64)::UAIModel
     rawlines = split(str, "\n")
     # Filter out empty lines
     lines = filter(!isempty, rawlines)
@@ -59,7 +59,7 @@ function read_instance_from_string(str::AbstractString; factor_eltype = Float64)
     # Wrap the tables with their corresponding scopes in an array of Factor type
     factors = [Factor{factor_eltype, length(scope)}(Tuple(scope), table) for (scope, table) in zip(scopes_sorted, tables_sorted)]
 
-    return UAIInstance(nvars, ntables, cards, factors)
+    return UAIModel(nvars, ntables, cards, factors)
 end
 
 """
@@ -125,7 +125,7 @@ end
 $(TYPEDSIGNATURES)
 
 Parse the solution marginals of all variables from the UAI MAR solution file.
-The order of the variables is the same as in the instance definition.
+The order of the variables is the same as in the model definition.
 
 The UAI file formats are defined in:
 https://uaicompetition.github.io/uci-2022/file-formats/
@@ -190,8 +190,8 @@ broadcasted_content(x) = asarray(content.(x), x)
 """
 $TYPEDEF
 
-Specify the UAI instances from the artifacts.
-It can be used as the input of [`read_instance`](@ref).
+Specify the UAI models from the artifacts.
+It can be used as the input of [`read_model`](@ref).
 
 ### Fields
 $TYPEDFIELDS
@@ -217,11 +217,11 @@ end
 """
 $TYPEDSIGNATURES
 
-Read an UAI instance from an artifact.
+Read an UAI model from an artifact.
 """
-function read_instance(instance::ArtifactProblemSpec; eltype=Float64)
-    problem_name = "$(instance.problem_set)_$(instance.problem_id).uai"
-    return read_instance_file(joinpath(instance.artifact_path, instance.task, problem_name); factor_eltype = eltype)
+function read_model(problem::ArtifactProblemSpec; eltype=Float64)
+    problem_name = "$(problem.problem_set)_$(problem.problem_id).uai"
+    return read_model_file(joinpath(problem.artifact_path, problem.task, problem_name); factor_eltype = eltype)
 end
 
 """
@@ -232,21 +232,21 @@ Return the solution in the artifact.
 The UAI file formats are defined in:
 https://uaicompetition.github.io/uci-2022/file-formats/
 """
-function read_solution(instance::ArtifactProblemSpec; factor_eltype=Float64)
-    problem_name = "$(instance.problem_set)_$(instance.problem_id).uai.$(instance.task)"
-    solution_filepath = joinpath(instance.artifact_path, instance.task, problem_name)
+function read_solution(problem::ArtifactProblemSpec; factor_eltype=Float64)
+    problem_name = "$(problem.problem_set)_$(problem.problem_id).uai.$(problem.task)"
+    solution_filepath = joinpath(problem.artifact_path, problem.task, problem_name)
 
     # Read the solution file into an array of lines
     rawlines = open(solution_filepath) do file
         readlines(file)
     end
 
-    if instance.task == "MAR" || instance.task == "MAR2"
+    if problem.task == "MAR" || problem.task == "MAR2"
         return parse_mar_solution_file(rawlines; factor_eltype)
-    elseif instance.task == "MAP" || instance.task == "MMAP"
+    elseif problem.task == "MAP" || problem.task == "MMAP"
         # Return all elements except the first in the last line as a vector of integers
         return last(rawlines) |> split |> x -> x[2:end] |> x -> parse.(Int, x)
-    elseif instance.task == "PR"
+    elseif problem.task == "PR"
         # Parse the number in the last line as a floating point
         return last(rawlines) |> x -> parse(Float64, x)
     end
@@ -255,19 +255,19 @@ end
 """
 $TYPEDSIGNATURES
 """
-function read_evidence(instance::ArtifactProblemSpec)
-    problem_name = "$(instance.problem_set)_$(instance.problem_id).uai.evid"
-    evidence_filepath = joinpath(instance.artifact_path, instance.task, problem_name)
+function read_evidence(problem::ArtifactProblemSpec)
+    problem_name = "$(problem.problem_set)_$(problem.problem_id).uai.evid"
+    evidence_filepath = joinpath(problem.artifact_path, problem.task, problem_name)
     obsvars, obsvals = read_evidence_file(evidence_filepath)
     return Dict(zip(obsvars, obsvals))
 end
 
 """
 $TYPEDSIGNATURES
 """
-function read_queryvars(instance::ArtifactProblemSpec)
-    problem_name = "$(instance.problem_set)_$(instance.problem_id).uai.query"
-    query_filepath = joinpath(instance.artifact_path, instance.task, problem_name)
+function read_queryvars(problem::ArtifactProblemSpec)
+    problem_name = "$(problem.problem_set)_$(problem.problem_id).uai.query"
+    query_filepath = joinpath(problem.artifact_path, problem.task, problem_name)
     return read_query_file(query_filepath)
 end