add the docs

docs/src/clh.md

@@ -1,7 +1,7 @@
 # Introduction
 A clustered Hamiltonian is a graphical representation that allows for a convenient and intuitive way to describe the structure of a network.
 
-The concept of a clustered Hamiltonian within `SpinGlassNetworks.jl` introduces a powerful mechanism for organizing spins into desired geometries, facilitating a structured approach to modeling complex spin systems. Analogous to a factor graph, the clustered Hamiltonian involves nodes that represent tensors within the underlying network. The edges connecting these nodes in the clustered Hamiltonian correspond to the indices shared between the respective tensors in the tensor network.
+The concept of a clustered Hamiltonian within `SpinGlassNetworks.jl` introduces a mechanism for organizing spins into desired geometries, facilitating a structured approach to modeling complex spin systems. Analogous to a standard factor graph, the clustered Hamiltonian involves nodes that represent tensors within the underlying network. The edges connecting these nodes in the clustered Hamiltonian correspond to the indices shared between the respective tensors in the tensor network.
 
 ```@docs
 clustered_hamiltonian

docs/src/ising.md

@@ -12,7 +12,7 @@ ising_graph
 ```
 
 ## Simple example
-In this simple example below we show how to create Ising graph of a instance given as txt file in a format (i, j, Jij). The resulting graph has vertices (black circles) corresponding to positions of spins in the system and edges defining coupling strength between spins. Each vertex contains information about local field.
+In this simple example below we show how to create Ising graph of a instance given as txt file in a format (i, j, Jij). The resulting graph has vertices corresponding to positions of spins in the system and edges defining coupling strength between spins. Each vertex contains information about local field.
 
 ```@example
 using SpinGlassNetworks

docs/src/lattice.md

@@ -1,10 +1,10 @@
-## Lattice geometries
-The Ising graph allowed for loading instances directly from a file and translating it 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 clustered Hamiltonian.
-Within the `SpinGlassNetworks.jl` package, users have the flexibility to construct various lattice geometries, each tailored to specific needs. With these diverse lattice geometries, SpinGlassNetworks empowers users to model and study complex spin systems with a high degree of flexibility and precision. 
+# 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 clustered Hamiltonian.
+Within the `SpinGlassNetworks.jl` package, users have the flexibility to construct three types of lattice geometries, each tailored to specific needs. 
 
 ## 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 a nuanced exploration of spin interactions beyond the traditional square lattice framework. 
+This geometry allows for an exploration of spin interactions beyond the traditional square lattice framework. 
 ```@raw html
 <img src="../images/sd.pdf" width="200%" class="center"/>
 ```

docs/src/userguide.md

@@ -2,4 +2,4 @@
 
 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.
 
-The contents of our package are richly 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 `clustered_hamiltonian` function is presented as a pivotal tool for converting Ising graphs into clustered 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 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 `clustered_hamiltonian` function is presented as a tool for converting Ising graphs into clustered 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.

src/bp.jl

@@ -13,23 +13,22 @@ export
 
 """
 $(TYPEDSIGNATURES)
-Perform belief propagation on a given clustered hamiltonian.
+Perform loopy belief propagation on a given clustered Hamiltonian.
 
 # Arguments:
-- `cl_h::LabelledGraph{S, T}`: The clustered hamiltonian represented as a labeled graph.
-- `beta::Real`: The temperature parameter for the belief propagation algorithm.
-- `tol::Real (optional, default=1e-6)`: The convergence tolerance. 
-The algorithm stops when the message updates between iterations are smaller than this value.
+- `cl_h::LabelledGraph{S, T}`: The clustered Hamiltonian represented as a labelled graph.
+- `beta::Real`: The inverse temperature parameter for the belief propagation algorithm.
+- `tol::Real (optional, default=1e-6)`: The convergence tolerance. The algorithm stops when the message updates between iterations are smaller than this value.
 - `iter::Int (optional, default=1)`: The maximum number of iterations to perform.
 
 # Returns:
 - `beliefs::Dict`: A dictionary where keys are vertices of clustered hamiltonian, and values are the 
 resulting beliefs after belief propagation.
 
-The function implements belief propagation on the given clustered hamiltonian `cl_h` to calculate beliefs for each vertex.
+The function implements loopy belief propagation on the given clustered hamiltonian `cl_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 clustered hamiltonian. 
 The algorithm continues until convergence or until the specified maximum number of iterations is reached.
-The beliefs are computed based on the temperature parameter `beta`, which controls the influence of energy values on the beliefs.
+The beliefs are computed based on the inverse temperature parameter `beta`, which controls the influence of energy values on the beliefs.
 """
 function belief_propagation(cl_h::LabelledGraph{S, T}, beta::Real; tol=1e-6, iter=1)  where {S, T}
     messages_ve = Dict()
@@ -247,17 +246,17 @@ end
 """
 $(TYPEDSIGNATURES)
 
-Constructs a clustered Hamiltonian for a given clustered Hamiltonian with a 2-site cluster approximation.
+Constructs a clustered Hamiltonian for a given clustered Hamiltonian with a 2-site cluster approximation used in Pegasus graph.
 
 # Arguments:
-- `cl_h::LabelledGraph{S, T}`: The clustered Hamiltonian represented as a labeled graph.
-- `beta::Real`: The temperature parameter for the 2-site cluster Hamiltonian construction.
+- `cl_h::LabelledGraph{S, T}`: The clustered Hamiltonian represented as a labelled graph.
+- `beta::Real`: The inverse temperature parameter for the 2-site cluster Hamiltonian construction.
     
 # Returns:
-- `new_cl_h::LabelledGraph{MetaDiGraph}`: A new labeled graph representing the 2-site cluster Hamiltonian.
+- `new_cl_h::LabelledGraph{MetaDiGraph}`: A new labelled graph representing the 2-site cluster Hamiltonian.
     
- This function constructs a clustered Hamiltonian `cl_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.
+This function constructs a clustered Hamiltonian `cl_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_cl_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 

src/clustered_hamiltonian.jl

@@ -46,19 +46,17 @@ This function constructs a clustered Hamiltonian from an Ising graph by introduc
 
 # Arguments:
 - `ig::IsingGraph`: The Ising graph representing the spin system.
-- `num_states_cl::Int`: The number of states per cluster.
-- `spectrum::Function`: A function for calculating the spectrum of the clustered Hamiltonian.
-- `cluster_assignment_rule::Dict{Int, L}`: A dictionary specifying the assignment rule that maps Ising graph vertices to clusters.
+- `num_states_cl::Int`: The number of states per cluster taken into account when calculating the spectrum. In every cluster the number of states is constant.
+- `spectrum::Function`: A function for calculating the spectrum of the clustered Hamiltonian. It can be `full_spectrum` or `brute_force`.
+- `cluster_assignment_rule::Dict{Int, L}`: A dictionary specifying the assignment rule that maps Ising graph vertices to clusters. It can be `super_square_lattice`, `pegasus_lattice` or `zephyr_lattice`.
 
 # Returns:
-- `cl_h::LabelledGraph{S, T}`: The clustered Hamiltonian represented as a labeled graph.
+- `cl_h::LabelledGraph{S, T}`: The clustered Hamiltonian represented as a labelled graph.
 
 The `clustered_hamiltonian` function takes an Ising graph (`ig`) as input and constructs a clustered Hamiltonian by 
 introducing a natural order in clustered Hamiltonian coordinates. 
 It allows you to specify the number of states per cluster, a spectrum calculation function, 
 and a cluster assignment rule, which maps Ising graph vertices to clusters.
-
-This function is useful for organizing and studying spin systems in a clustered Hamiltonian framework.
 """
 function clustered_hamiltonian(
     ig::IsingGraph,
@@ -79,18 +77,17 @@ This function constructs a clustered Hamiltonian from an Ising graph by introduc
 
 # Arguments:
 - `ig::IsingGraph`: The Ising graph representing the spin system.
-- `num_states_cl::Dict{T, Int}`: A dictionary specifying the number of states per cluster for different clusters.
-- `spectrum::Function`: A function for calculating the spectrum of the clustered Hamiltonian.
-- `cluster_assignment_rule::Dict{Int, T}`: A dictionary specifying the assignment rule that maps Ising graph vertices to clusters.
+- `num_states_cl::Dict{T, Int}`: A dictionary specifying the number of states per cluster for different clusters. Number of states are considered when calculating the spectrum.
+- `spectrum::Function`: A function for calculating the spectrum of the clustered Hamiltonian. It can be `full_spectrum` or `brute_force`.
+- `cluster_assignment_rule::Dict{Int, T}`: A dictionary specifying the assignment rule that maps Ising graph vertices to clusters. It can be `super_square_lattice`, `pegasus_lattice` or `zephyr_lattice`.
 
 # Returns:
-- `cl_h::LabelledGraph{MetaDiGraph}`: The clustered Hamiltonian represented as a labeled graph.
+- `cl_h::LabelledGraph{MetaDiGraph}`: The clustered Hamiltonian represented as a labelled graph.
 
 The `clustered_hamiltonian` function takes an Ising graph (`ig`) as input and constructs a clustered Hamiltonian 
 by introducing a natural order in clustered Hamiltonian coordinates. It allows you to specify the number of 
-states per cluster, a spectrum calculation function, and a cluster assignment rule, which maps Ising graph vertices to clusters.
-
-This function is useful for organizing and studying spin systems in a clustered Hamiltonian framework.
+states per cluster which can vary for different clusters, a spectrum calculation function, 
+and a cluster assignment rule, which maps Ising graph vertices to clusters.
 
 """
 function clustered_hamiltonian(
@@ -149,20 +146,18 @@ This function constructs a clustered Hamiltonian from an Ising graph by introduc
 
 # Arguments:
 - `ig::IsingGraph`: The Ising graph representing the spin system.
-- `spectrum::Function`: A function for calculating the spectrum of the clustered Hamiltonian.
-- `cluster_assignment_rule::Dict{Int, T}`: A dictionary specifying the assignment rule that maps Ising graph vertices to clusters.
+- `spectrum::Function`: A function for calculating the spectrum of the clustered Hamiltonian. It can be `full_spectrum` or `brute_force`. Default is `full_spectrum`.
+- `cluster_assignment_rule::Dict{Int, T}`: A dictionary specifying the assignment rule that maps Ising graph vertices to clusters. It can be `super_square_lattice`, `pegasus_lattice` or `zephyr_lattice`.
 
 # Returns:
-- `cl_h::LabelledGraph{MetaDiGraph}`: The clustered Hamiltonian represented as a labeled graph.
+- `cl_h::LabelledGraph{MetaDiGraph}`: The clustered Hamiltonian represented as a labelled graph.
 
 The `clustered_hamiltonian` function takes an Ising graph (`ig`) as input and constructs a clustered Hamiltonian 
 by introducing a natural order in clustered Hamiltonian coordinates. 
 You can optionally specify a spectrum calculation function and a cluster assignment rule, which maps Ising graph vertices to clusters.
-
+This version of `clustered_hamiltonian` function does not truncate states in the cluster while calculating the spectrum.
 If you want to specify custom cluster sizes, use the alternative version of this function by 
 passing a `Dict{T, Int}` containing the number of states per cluster as `num_states_cl`.
-
-This function is useful for organizing and studying spin systems in a clustered Hamiltonian framework.
 """
 function clustered_hamiltonian(
     ig::IsingGraph; 

src/ising.jl

@@ -26,7 +26,8 @@ $(TYPEDSIGNATURES)
 Create an Ising graph from interaction data.
 
 This function creates an Ising graph (LabelledGraph) from interaction data provided in the form of an `inst` argument.
-The Ising graph represents a system of spins, where each spin is associated with a vertex, and interactions between spins are represented as edges with corresponding weights.
+The Ising graph represents a system of spins, where each spin is associated with a vertex, 
+and interactions between spins are represented as edges with corresponding weights.
 
 # Arguments:
 - `::Type{T}`: The type of the edge weights, typically `Float64` or `Float32`.
@@ -38,7 +39,7 @@ The Ising graph represents a system of spins, where each spin is associated with
 - `ig::IsingGraph{T}`: The Ising graph (LabelledGraph) representing the spin system.
 
 The function reads interaction data and constructs an Ising graph `ig`.
-It assigns interaction strengths to edges between spins and optionally scales them by the `scale` factor.
+It assigns interaction strengths to edges between spins and optionally scales them by the `scale` factor. 'Scale' option allows for the change of convention in the Hamiltonian.
 The `rank_override` dictionary can be used to specify the rank (number of states) for individual vertices, allowing customization of the Ising model.
 Convention: H = scale * sum_{i, j} (J_{ij} * s_i * s_j + J_{ii} * s_i)
 """