Docs (#20)

* rewrite lattice.md

* rewrite potts hamiltonian docs

* rewrite LBP

* rewrite lbp

* rewrite truncate_potts_hamiltonian

* rewrite decode_potts_hamiltonian_state

---------

Co-authored-by: annamariadziubyna <anna.maria.dziubyna@doctoral.uj.edu.pl>

docs/src/api.md

@@ -14,14 +14,12 @@ couplings
 ## Potts Hamiltonian
 ```@docs
 split_into_clusters
-decode_potts_hamiltonian_state
 rank_reveal
 energy
 energy_2site
 cluster_size
 bond_energy
 exact_cond_prob
-truncate_potts_hamiltonian
 ```
 
 ## Belief propagation

docs/src/bp.md

@@ -1,7 +1,10 @@
-## Belief propagation
-The `SpinGlassPEPS.jl` package is capable of handling clusters with up to 24 spins, which results in a total of 2^24 degrees of freedom per cluster. This makes the contraction of the tensor network generated from such a Hamiltonian computationally expensive. To address this, `SpinGlassPEPS.jl` offers an optional feature for local dimensional reduction of cluster degrees of freedom by selectively choosing the most probable states within each cluster. This method reduces the dimensionality of the problem by focusing on the most relevant and energetically favorable states. The marginal probabilities of each Potts variable are approximated using the Loopy Belief Propagation (LBP) algorithm.
+## Local dimensional reduction of cluster degrees of freedom
+The `SpinGlassPEPS.jl` package addresses the computational challenges posed by large unit cells, which result in a high number of degrees of freedom per cluster. Contracting tensor networks generated from such Hamiltonians can become numerically expensive. To mitigate this, the package provides an optional local dimensional reduction feature, which reduces the problem's complexity by focusing on the most probable states within each cluster.
+
+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

docs/src/clh.md

@@ -1,7 +1,5 @@
 # Introduction
-A Potts Hamiltonian is a graphical representation that allows for a convenient and intuitive way to describe the structure of a network.
-
-The concept of a Potts Hamiltonian within `SpinGlassNetworks.jl` introduces a mechanism for organizing spins into desired clustered geometries, facilitating a structured approach to modeling complex spin systems. 
+In `SpinGlassNetworks.jl`, the Potts Hamiltonian serves as a framework for transforming Ising graphs into clustered representations, enabling efficient modeling of complex spin systems. Instead of treating individual spins as separate variables, spins are grouped into clusters corresponding to unit cells of a given lattice geometry. This process reduces the number of variables while increasing their dimensionality, making the system more manageable for tensor-network-based approaches.
 
 ```@docs
 potts_hamiltonian

docs/src/lattice.md

@@ -1,10 +1,11 @@
 # Lattice geometries
-The Ising graph allowed for loading instances directly from a file and translating them into a graph. The next step towards constructing the tensor network is to build a lattice, based on which we will transform the Ising graph into a Potts Hamiltonian.
-Within the `SpinGlassNetworks.jl` package, users have the flexibility to construct three types of lattice geometries, each tailored to specific needs. 
+The Ising graph serves as the starting point, allowing users to load instances directly from a file and translate them into a graph with vertices numerated using linear indices. To group spins into clusters for the Potts Hamiltonian, it is necessary to map these linear spin coordinates onto the corresponding coordinates of a Potts clusters in a specific lattice geometry. 
+
+The `SpinGlassNetworks.jl` package provides tools for mapping linear indices into three types of lattice geometries, enabling users to adapt the mapping process to the structure of the problem being analyzed. These geometries include super square lattice, Pegasus lattice, and Zephyr lattice, each optimized for specific topologies and applications. For example, in the Pegasus lattice, groups of 24 binary spins are clustered into a single Potts variable, while in the Zephyr lattice, clusters consist of 16 binary spins. 
 
 ## Super square lattice
-The `super_square_lattice` geometry represents a square lattice with nearest neighbors interactions (horizontal and vertical interactions between unit cells) and next nearest neighbor interactions (diagonal interactions). Unit cells depicted on the schematic picture below as red ellipses can consist of multiple spins.
-This geometry allows for an exploration of spin interactions beyond the traditional square lattice framework. 
+The `super_square_lattice` geometry defines a square lattice with interactions between nearest neighbors (horizontal and vertical connections between unit cells) and next-nearest neighbors (diagonal connections). In `super_square_lattice` function, linear indices of spins from the Ising graph are mapped onto a 2D super square lattice coordinate system (King's lattice). 
+Spins (denoted as black dots in the figure below) are grouped into clusters represented as red ellipses. Every spin in this cluster is indexed coresponding to the square lattice coordinate in the new graph with reduced number of variables of higher dimensions (shown on the right).
 ```@raw html
 <img src="../images/sd.png" width="200%" class="center"/>
 ```

docs/src/userguide.md

@@ -1,5 +1,5 @@
 # Introduction
 
-A [Julia](http://julialang.org) package for building and interacting with Ising spin glass models in context of tensor networks. Part of [SpinGlassPEPS](https://github.com/euro-hpc-pl/SpinGlassPEPS.jl) package.
+A [Julia](http://julialang.org) package for generating an Ising graphs and clustering binary variables to create effective Potts Hamiltonians. Part of [SpinGlassPEPS](https://github.com/euro-hpc-pl/SpinGlassPEPS.jl) package.
 
-The contents of our package are illustrated through comprehensive examples, showcasing the practical utilization of key functions. Specifically, the `ising_graph` function is highlighted, demonstrating its capacity to generate Ising model graphs — a fundamental step in modeling spin systems. Additionally, the `potts_hamiltonian` function is presented as a tool for converting Ising graphs into Potts Hamiltonians. The package delves into various lattice geometries, providing insights into constructing diverse structures such as the `super_square_lattice`, `pegasus_lattice`, and `zephyr_lattice`. Moreover, the documentation outlines methods for local dimensional reduction, shedding light on techniques to streamline computations and enhance the efficiency of spin system simulations.
+The contents of `SpinGlassNetworks.jl` package is illustrated through comprehensive examples, showcasing the practical utilization of key functions. Specifically, the `ising_graph` function is highlighted, demonstrating its capacity to generate Ising graphs from a given instance using a set of standard inputs (e.g., instances compatible with the Ocean environment provided by D-Wave). Additionally, the `potts_hamiltonian` function is presented as a tool for grouping binary variables into clusters with a reduced number of variables of larger dimensions, creating effective Potts Hamiltonians. The package delves into various lattice geometries, providing reindexing of linear Ising coordinates into `super_square_lattice`, `pegasus_lattice`, and `zephyr_lattice`. Moreover, the documentation outlines methods for local dimensional reduction of cluster degrees of freedom.

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/lattice.jl

@@ -8,25 +8,6 @@ export super_square_lattice,
     zephyr_lattice_5tuple_rotated,
     periodic_lattice
 
-"""
-$(TYPEDSIGNATURES)
-
-Create a mapping from Ising graph coordinates to a super square lattice arrangement.
-Variable number of Ising graph -> cluster hamiltonian coordinate system
-
-This function generates a mapping that relates Ising graph coordinates to a super square lattice arrangement. 
-The super square lattice is defined by the size of five dimensions: `(m, um, n, un, t)`,
-where m is the number of columns, n is the number of rows and t denotes the number of spins stored in the cluster.
-
-# Arguments:
-- `size::NTuple{5, Int}`: A tuple specifying the size of the super square lattice in five dimensions: `(m, um, n, un, t)`.
-
-# Returns:
-- `coord_map::Dict`: A dictionary that maps Ising graph coordinates to the corresponding lattice coordinates.
-
-The `size` tuple represents the dimensions of the super square lattice. The function creates a dictionary where 
-ising graph coordinates are associated with their corresponding lattice coordinates.
-"""
 function super_square_lattice(size::NTuple{5,Int})
     m, um, n, un, t = size
     old = LinearIndices((1:t, 1:un, 1:n, 1:um, 1:m))
@@ -36,20 +17,17 @@ end
 """
 $(TYPEDSIGNATURES)
 
-Create a mapping from Ising graph coordinates to a simplified super square lattice arrangement.
+Create a mapping from Ising graph coordinates to a super square lattice arrangement.
 
-This function generates a mapping that relates Ising graph coordinates to a simplified super square lattice arrangement. 
-The simplified super square lattice is defined by the size of three dimensions: `(m, n, t)`, where m is the number of columns, 
-n is the number of rows and t denotes the number of spins stored in the cluster.
+This function generates a mapping that relates linear Ising graph coordinates to a super square lattice arrangement. 
+The super square lattice is defined by the size of three dimensions: `(m, n, t)`, where `m` is the number of columns, 
+`n` is the number of rows and `t` denotes the number of spins stored in the cluster.
 
 # Arguments:
-- `size::NTuple{3, Int}`: A tuple specifying the size of the simplified super square lattice in three dimensions: `(m, n, t)`, where `m` is number of columns, `n` number of rows and `t` denotes number of spins in cluster.
+- `size::NTuple{3, Int}`: A tuple specifying the size of the super square lattice in three dimensions: `(m, n, t)`, where `m` is number of columns, `n` number of rows and `t` denotes number of spins in cluster.
 
 # Returns:
 - `coord_map::Dict`: A dictionary that maps Ising graph coordinates to the corresponding lattice coordinates.
-
-The `size` tuple represents the dimensions of the simplified super square lattice. 
-The function internally adds the required dimensions `(1, 1)` to make it compatible with the `super_square_lattice` function, which deals with five dimensions.
 """
 function super_square_lattice(size::NTuple{3,Int})
     m, n, t = size
@@ -67,10 +45,12 @@ This function generates a mapping that relates Ising graph coordinates to Pegasu
 based on the specified size of the Pegasus lattice in three dimensions: `(m, n, t)`.
 
 # Arguments:
-- `size::NTuple{3, Int}`: A tuple specifying the size of the Pegasus lattice in three dimensions: `(m, n, t)`, where `m` is number of columns, `n` number of rows and `t` denotes number of spins in the cluster. One Pegasus cluster consists of 24 spins. Convention: `t` is already divided by 8, so `t`=3 for Pegasus lattice.
+- `size::NTuple{3, Int}`: A tuple specifying the size of the Pegasus lattice in three dimensions: `(m, n, t)`, where `m` is number of columns, `n` number of rows and `t` denotes number of spins in the cluster. 
+One Pegasus cluster consists of 24 spins. 
+Convention: `t` is already divided by 8, so `t`=3 for Pegasus lattice.
 
 # Returns:
-- `coord_map::Dict`: A dictionary that maps Ising graph coordinates to the corresponding Pegasus lattice coordinates.
+- `coord_map::Dict`: A dictionary that maps linear Ising graph coordinates to the corresponding Pegasus lattice coordinates.
 
 The `pegasus_lattice` allows you to build the graph relevant for D-Wave Pegasus architecture.
 """
@@ -156,11 +136,14 @@ $(TYPEDSIGNATURES)
 
 Create a mapping from Ising graph coordinates to Zephyr lattice coordinates.
 
-This function generates a mapping that relates Ising graph coordinates to Zephyr lattice 
+This function generates a mapping that relates linear Ising graph coordinates to Zephyr lattice 
 coordinates based on the specified size of the Zephyr lattice in three dimensions: `(m, n, t)`.
 
 # Arguments:
-- `size::NTuple{3, Int}`: A tuple specifying the size of the Zephyr lattice in three dimensions: `(m, n, t)`, where `m` is double number of columns, `n` double number of rows and `t` denotes number of spins in cluster. One full Zephyr cluster consists of 16 spins. Convention: `t` is already divided by 4, so `t`=4 for Zephyr lattice. E.g. to create 3x3x16 Zephyr lattice, you should use `m`=6, `n`=6, `t`=4.
+- `size::NTuple{3, Int}`: A tuple specifying the size of the Zephyr lattice in three dimensions: `(m, n, t)`, where `m` is double number of columns, `n` double number of rows and `t` denotes number of spins in cluster. 
+One full Zephyr cluster consists of 16 spins. 
+Convention: `t` is already divided by 4, so `t`=4 for Zephyr lattice. 
+E.g. to create 3x3x16 Zephyr lattice, you should use `m`=6, `n`=6, `t`=4.
 
 # Returns:
 - `coord_map::Dict`: A dictionary that maps Ising graph coordinates to the corresponding Zephyr lattice coordinates.