fix docs

Author: GiggleLiu

docs/src/api/public.md

@@ -43,6 +43,7 @@ RescaledArray
 TensorNetworkModel
 ArtifactProblemSpec
 UAIModel
+BeliefPropgation
 ```
 
 ## Functions
@@ -56,6 +57,7 @@ marginals
 maximum_logp
 most_probable_config
 probability
+belief_propagate
 dataset_from_artifact
 problem_from_artifact
 read_model
@@ -69,4 +71,6 @@ sample
 update_evidence!
 update_temperature
 random_matrix_product_state
+random_matrix_product_uai
+random_tensor_train_uai
 ```

docs/src/tensor-networks.md

@@ -205,6 +205,13 @@ Some of these have been implemented in the
 [OMEinsum](https://github.com/under-Peter/OMEinsum.jl) package. Please check
 [Performance Tips](@ref) for more details.
 
+## Belief propagation
+
+Belief propagation[^Yedidia2003] is a message passing algorithm that can be used to compute the marginals of a probabilistic graphical model. It has close connections with the tensor networks. It can be viewed as a way to gauge the tensor networks[^Tindall2023], and can be combined with tensor networks to achieve better performance[^Wang2024].
+
+Belief propagation is an approximate method, and the quality of the approximation can be improved by the loop series expansion[^Evenbly2024].
+
+
 ## References
 
 [^Orus2014]:
@@ -227,3 +234,15 @@ Some of these have been implemented in the
 
 [^Liu2023]:
     Liu J G, Gao X, Cain M, et al. Computing solution space properties of combinatorial optimization problems via generic tensor networks[J]. SIAM Journal on Scientific Computing, 2023, 45(3): A1239-A1270.
+
+[^Yedidia2003]:
+    Yedidia, J.S., Freeman, W.T., Weiss, Y., 2003. Understanding belief propagation and its generalizations, in: Exploring Artificial Intelligence in the New Millennium. Morgan Kaufmann Publishers Inc., San Francisco, CA, USA, pp. 239–269.
+
+[^Wang2024]:
+    Wang, Y., Zhang, Y.E., Pan, F., Zhang, P., 2024. Tensor Network Message Passing. Phys. Rev. Lett. 132, 117401. https://doi.org/10.1103/PhysRevLett.132.117401
+
+[^Tindall2023]:
+    Tindall, J., Fishman, M.T., 2023. Gauging tensor networks with belief propagation. SciPost Phys. 15, 222. https://doi.org/10.21468/SciPostPhys.15.6.222
+
+[^Evenbly2024]:
+    Evenbly, G., Pancotti, N., Milsted, A., Gray, J., Chan, G.K.-L., 2024. Loop Series Expansions for Tensor Networks. https://doi.org/10.48550/arXiv.2409.03108

src/belief.jl

@@ -1,3 +1,14 @@
+"""
+$TYPEDEF
+    BeliefPropgation(nvars::Int, t2v::AbstractVector{Vector{Int}}, tensors::AbstractVector{AbstractArray{T}}) where T
+
+A belief propagation object.
+
+### Fields
+- `t2v::Vector{Vector{Int}}`: a mapping from tensors to variables
+- `v2t::Vector{Vector{Int}}`: a mapping from variables to tensors
+- `tensors::Vector{AbstractArray{T}}`: the tensors
+"""
 struct BeliefPropgation{T}
     t2v::Vector{Vector{Int}}           # a mapping from tensors to variables
     v2t::Vector{Vector{Int}}           # a mapping from variables to tensors
@@ -16,6 +27,12 @@ function BeliefPropgation(nvars::Int, t2v::AbstractVector{Vector{Int}}, tensors:
     end
     return BeliefPropgation(t2v, v2t, tensors)
 end
+
+"""
+$(TYPEDSIGNATURES)
+
+Construct a belief propagation object from a [`UAIModel`](@ref).
+"""
 function BeliefPropgation(uai::UAIModel{T}) where T
     return BeliefPropgation(uai.nvars, [collect(Int, f.vars) for f in uai.factors], AbstractArray{T}[f.vals for f in uai.factors])
 end
@@ -83,7 +100,18 @@ function initial_state(bp::BeliefPropgation{T}) where T
     return BPState(deepcopy(edges_vectors), edges_vectors)
 end
 
-# belief propagation, update the tensors on the edges of the tensor network
+"""
+$(TYPEDSIGNATURES)
+
+Run the belief propagation algorithm, and return the final state and the information about the convergence.
+
+### Arguments
+- `bp::BeliefPropgation`: the belief propagation object
+
+### Keyword Arguments
+- `max_iter::Int=100`: the maximum number of iterations
+- `tol::Float64=1e-6`: the tolerance for the convergence
+"""
 function belief_propagate(bp::BeliefPropgation; max_iter::Int=100, tol::Float64=1e-6)
     state = initial_state(bp)
     info = belief_propagate!(bp, state; max_iter=max_iter, tol=tol)
@@ -112,6 +140,9 @@ function contraction_results(state::BPState{T}) where T
     return [sum(reduce((x, y) -> x .* y, mi)) for mi in state.message_in]
 end
 
+"""
+$(TYPEDSIGNATURES)
+"""
 function marginals(state::BPState{T}) where T
     return Dict([v] => normalize!(reduce((x, y) -> x .* y, mi), 1) for (v, mi) in enumerate(state.message_in))
 end

src/utils.jl

@@ -339,6 +339,12 @@ function random_matrix_product_state(::Type{T}, n::Int, chi::Int, d::Int=2) wher
 end
 random_matrix_product_state(n::Int, chi::Int, d::Int=2) = random_matrix_product_state(ComplexF64, n, chi, d)
 
+"""
+$TYPEDSIGNATURES
+
+Generate a random UAIModel that represents a matrix product state (MPS).
+Similar to [`random_matrix_product_state`](@ref), but returns the UAIModel directly.
+"""
 function random_matrix_product_uai(::Type{T}, n::Int, chi::Int, d::Int=2) where T
     # chi ^ (n-1) * (variance^n)^2 == 1/d^n
     variance = d^(-1/2) * chi^(-1/2+1/2n)