rewrite truncate_potts_hamiltonian

docs/src/api.md

@@ -21,7 +21,6 @@ energy_2site
 cluster_size
 bond_energy
 exact_cond_prob
-truncate_potts_hamiltonian
 ```
 
 ## Belief propagation

docs/src/bp.md

@@ -4,6 +4,7 @@ The `SpinGlassPEPS.jl` package addresses the computational challenges posed by l
 This dimensionality reduction is achieved by approximating the marginal probabilities of Potts variables using the Loopy Belief Propagation (LBP) algorithm. LBP iteratively updates messages between clusters and edges to approximate the likelihood of configurations within each cluster. While exact convergence is guaranteed only for tree-like graphs, this method effectively selects a subset of energetically favorable states, even for geometries with loops, such as Pegasus and Zephyr lattices. The details of the Loopy Belief Propagation algorithm are described in [Ref.](https://arxiv.org/abs/2411.16431)
 
 ```@docs
+truncate_potts_hamiltonian
 potts_hamiltonian_2site
 belief_propagation
 truncate_potts_hamiltonian_2site_BP

src/bp.jl

@@ -21,8 +21,7 @@ Perform loopy belief propagation on a given Potts Hamiltonian.
 - `iter::Int (optional, default=1)`: The maximum number of iterations to perform.
 
 # Returns:
-- `beliefs::Dict`: A dictionary where keys are vertices of Potts Hamiltonian, and values are the 
-resulting beliefs after belief propagation.
+- `beliefs::Dict`: A dictionary mapping the vertices of the Potts Hamiltonian to the computed belief distributions of states within each cluster.
 
 The function implements loopy belief propagation on the given Potts Hamiltonian `potts_h` to calculate beliefs for each vertex.
 Belief propagation is an iterative algorithm that computes beliefs by passing messages between vertices and edges of the Potts Hamiltonian. 
@@ -255,21 +254,20 @@ end
 """
 $(TYPEDSIGNATURES)
 
-Constructs a Potts Hamiltonian for a given Potts Hamiltonian with a 2-site cluster approximation used in Pegasus graph.
+Construct a 2-site cluster approximation of a Potts Hamiltonian.
+
+This function generates a new Potts Hamiltonian using a 2-site cluster approximation, specifically designed for geometries like Pegasus and Zephyr. 
+In these geometries, clusters in the original Potts Hamiltonian are subdivided into smaller sub-clusters, which are then merged into unified 2-site clusters. 
 
 # Arguments:
-- `potts_h::LabelledGraph{S, T}`: The Potts Hamiltonian represented as a labelled graph.
-- `beta::Real`: The inverse temperature parameter for the 2-site cluster Hamiltonian construction.
-    
+- `potts_h::LabelledGraph{S, T}`: The input Potts Hamiltonian represented as a labelled graph, where vertices correspond to individual sub-clusters and edges define interactions between them.
+- `beta::Real`: The inverse temperature parameter, used for computing the energy values and spectra of the 2-site clusters.
+
 # Returns:
-- `new_potts_h::LabelledGraph{MetaDiGraph}`: A new labelled graph representing the 2-site cluster Hamiltonian.
-    
-This function constructs a Potts Hamiltonian `potts_h` by applying a 2-site cluster approximation. 
-It combines and merges vertices and edges of the original graph to create a simplified representation of the Hamiltonian.
-    
-The resulting `new_potts_h` graph represents the 2-site cluster Hamiltonian with simplified interactions between clusters. 
-The energy values, projectors, and spectra associated with the new vertices and edges are computed based on 
-the provided temperature parameter `beta`.
+- `new_potts_h::LabelledGraph{MetaDiGraph}`: A labelled graph representing the new Potts Hamiltonian, where:
+  - Vertices: Represent unified 2-site clusters.
+  - Edges: Capture interactions between these clusters, including energy values and associated projectors.
+
 """
 function potts_hamiltonian_2site(potts_h::LabelledGraph{S,T}, beta::Real) where {S,T}
 

src/potts_hamiltonian.jl

@@ -422,26 +422,6 @@ function exact_cond_prob(
     sum(prob[findall([all(s[k] == v for (k, v) ∈ target_state) for s ∈ states])])
 end
 
-"""
-$(TYPEDSIGNATURES)
-
-Truncate a Potts Hamiltonian based on specified states.
-
-This function truncates a given Potts Hamiltonian by selecting a subset of states for each cluster based on the provided `states` dictionary. 
-The resulting truncated Hamiltonian contains only the selected states for each cluster.
-
-# Arguments:
-- `potts_h::LabelledGraph{S, T}`: The Potts Hamiltonian represented as a labeled graph.
-- `states::Dict`: A dictionary specifying the states to be retained for each cluster.
-
-# Returns:
-- `new_potts_h::LabelledGraph{MetaDiGraph}`: The truncated Potts Hamiltonian with reduced states.
-
-The function creates a new Potts Hamiltonian `new_potts_h` with the same structure as the input `potts_h`. 
-It then updates the spectrum of each cluster in `new_potts_h` by selecting the specified states from the original spectrum. 
-Additionally, it updates the interactions and projectors between clusters based on the retained states. 
-The resulting `new_potts_h` represents a truncated version of the original Hamiltonian.
-"""
 function truncate_potts_hamiltonian(potts_h::LabelledGraph{S,T}, states::Dict) where {S,T}
 
     new_potts_h = LabelledGraph{MetaDiGraph}(vertices(potts_h))

src/truncate.jl

@@ -92,17 +92,20 @@ $(TYPEDSIGNATURES)
 
 Truncate a Potts Hamiltonian based on 2-site belief propagation states.
 
-This function truncates a Potts Hamiltonian by considering 2-site belief propagation states and selecting the most probable states 
-to keep. It computes the beliefs for all 2-site combinations and selects the states that maximize the probability.
+This function truncates the state space of a Potts Hamiltonian by leveraging 2-site belief propagation. 
+In certain geometries, such as Pegasus or Zephyr, clusters in the Potts Hamiltonian are further divided into smaller sub-clusters. 
+This function computes beliefs for the entire 2-site cluster and selects states that maximize the overall probability in a cluster.
 
 # Arguments:
 - `potts_h::LabelledGraph{S, T}`: The Potts Hamiltonian represented as a labelled graph.
-- `beliefs::Dict`: A dictionary containing belief values for 2-site interactions.
-- `num_states::Int`: The maximum number of most probable states to keep.
-- `beta::Real (optional)`: The inverse temperature parameter (default is 1.0).
+- `beliefs::Dict`: A dictionary where keys are clusters (vertices) and values are the beliefs.
+- `num_states::Int`: The maximum number of most probable states to retain for each cluster.
+- `result_folder::String (optional)`: Path to the folder where truncated states will be saved. Default is `"results_folder"`.
+- `inst::String (optional)`: Instance name for saving or loading results. Default is `"inst"`.
+- `beta::Real (optional)`: The inverse temperature parameter. Default is `1.0`.
 
 # Returns:
-- `LabelledGraph{S, T}`: A truncated Potts Hamiltonian.
+- `LabelledGraph{S, T}`: A Potts Hamiltonian with reduced state space, preserving only the most probable states.
 """
 function truncate_potts_hamiltonian_2site_BP(
     potts_h::LabelledGraph{S,T},
@@ -171,6 +174,26 @@ function select_numstate_best(E, sx, num_states)
     end
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+Truncate the Potts Hamiltonian using belief propagation or precomputed states.
+
+This function reduces the dimensionality of a given Potts Hamiltonian by truncating its states. 
+The process is guided by the Loopy Belief Propagation (LBP) algorithm, which estimates the marginal probabilities of states in the Potts model. If precomputed states are available, they are loaded from the specified result folder to skip recomputation.
+
+# Arguments:
+- `potts_h`: The input Potts Hamiltonian, represented as a labelled graph.
+- `β::Float64`: The inverse temperature parameter controlling the distribution of states.
+- `cs::Int`: The maximum number of states retained per cluster after truncation.
+- `result_folder::String`: The folder path where results are stored or loaded.
+- `inst::String`: The instance name used to identify stored results.
+- `tol::Float64`: (Optional) Convergence tolerance for the belief propagation algorithm. Default is `1e-6`.
+- `iter::Int`: The maximum number of iterations for the belief propagation algorithm.
+
+# Returns:
+- `potts_h`: A truncated Potts Hamiltonian with reduced state space, preserving the most relevant states per cluster.
+"""
 function truncate_potts_hamiltonian(
     potts_h,
     β,