add the docs

docs/make.jl

@@ -2,8 +2,8 @@ using Documenter, SpinGlassNetworks
 
 _pages = [
     "User guide" => "userguide.md",
-    "Lattice geometries" => "lattice.md",
     "Ising graph" => "ising.md",
+    "Lattice geometries" => "lattice.md",
     "Clustered hamiltonian" => "clh.md",
     "Local dimensional reduction" => "bp.md",
     "API Reference for auxiliary functions" => "api.md"

docs/src/clh.md

@@ -3,6 +3,16 @@ A clustered Hamiltonian is a graphical representation that allows for a convenie
 
 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 Ising problem in translates to:
+$$ H(\conf{x}{\Nbar}) = \sum_{\langle m,n\rangle \in \mathcal{F}} E_{x_m x_n} + \sum_{n=1}^{\Nbar} E_{x_n} $$
+$\mathcal{F}$ forms a 2D graph, see the figure below, where we indicate nearest-neighbour interactions with blue lines, and diagonal connections with green lines.
+Each $x_n$ takes $d$ values with  $d=2^4$ for square diagonal, $d=2^{24}$ for Pegasus and $2^{16}$ for Zephyr geometry. 
+$E_{x_n}$ is an intra--node energy of the corresponding binary-variables configuration, and $E_{x_n x_m}$ is inter--node energy.
+
+```@raw html
+<img src="../images/clh.pdf" width="200%" class="center"/>
+```
+
 ```@docs
 clustered_hamiltonian
 ```
@@ -13,13 +23,12 @@ clustered_hamiltonian
 using SpinGlassNetworks
 
 # Prepare simple instance
-instance = Dict((1, 1) => 1.0, (2, 2) => 0.5, (3, 3) => -0.25, 
-(1, 2) => -1.0, (2, 3) => 1.0)
+instance = "$(@__DIR__)/../../src/instances/square_diagonal/5x5/diagonal.txt"
 ig = ising_graph(instance)
 
 # Create clustered Hamiltonian.
 cl_h = clustered_hamiltonian(
     ig,
-    cluster_assignment_rule = super_square_lattice((3, 1, 1))
+    cluster_assignment_rule = super_square_lattice((5,5,4))
 )
 ```

docs/src/ising.md

@@ -1,25 +1,29 @@
-# Introduction
+# Ising model
 
 The Ising model is a mathematical model used to describe the behavior of interacting particles, such as atoms or molecules, in a magnetic field. In the Ising model, each particle is represented as a binary variable $s_i$ that can take on the values of either +1 or -1. The total energy of the system is given by the Hamiltonian:
 
 $$H =  \sum_{(i,j) \in \mathcal{E}} J_{ij} s_i s_j + \sum_{i} h_i s_i$$
 
 where $J_{ij}$ is the coupling constant between particles $i$ and $j$, $h_i$ is the external magnetic field at particle $i$, and the sum is taken over all pairs of particles and all particles in the system $\mathcal{E}$, respectively.
 
+In `SpinGlassPEPS.jl` package, an ising graph can be created using the command `ising_graph`.
 ```@docs
 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.
+
 ```@example
 using SpinGlassNetworks
 # Create Ising instance
-instance = Dict((1, 1) => 1.0, (2, 2) => 0.5, (3, 3) => -0.25, 
-(1, 2) => -1.0, (2, 3) => 1.0)
-
-# Generate Ising graph
+instance = "$(@__DIR__)/../../src/instances/square_diagonal/5x5/diagonal.txt"
 ig = ising_graph(instance)
 
 # View graph properties
 @show biases(ig), couplings(ig)
+```
+
+```@raw html
+<img src="../images/sd_ising.pdf" width="200%" class="center"/>
 ```

docs/src/lattice.md

@@ -1,21 +1,28 @@
-## Lattice
+## 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. 
 
 ## Super square lattice
-The `super_square_lattice` geometry represents a square lattice where unit cells consist of multiple spins, offering the unique feature of accommodating diagonal next-nearest-neighbor interactions. This geometry allows for a nuanced exploration of spin interactions beyond the traditional square lattice framework.
+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. 
+```@raw html
+<img src="../images/sd.pdf" width="200%" class="center"/>
+```
+
+In `SpinGlassPEPS.jl` solver, a grid of this type can be loaded using the command `super_square_lattice`.
 
 ```@docs
 super_square_lattice
 ```
 
+Below you find simple example of usage `super_square_latttice` function.
+
 ```@example
 using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs
 
-# load Chimera instance and create Ising graph
 instance = "$(@__DIR__)/../../src/instances/square_diagonal/5x5/diagonal.txt"
 ig = ising_graph(instance)
 
-# Loaded instance is zephyr graph
 m = 5
 n = 5
 t = 4
@@ -34,10 +41,14 @@ The Pegasus graph is a type of graph architecture used in quantum computing syst
 <img src="../images/peg.pdf" width="200%" class="center"/>
 ```
 
+In `SpinGlassPEPS.jl` solver, a grid of this type can be loaded using the command `pegasus_lattice`.
+
 ```@docs
 pegasus_lattice
 ```
 
+Below you find simple example of usage `pegasus_latttice` function.
+
 ```@example
 using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs
 
@@ -55,7 +66,7 @@ cl_h = clustered_hamiltonian(
     cluster_assignment_rule = pegasus_lattice((m, n, t))
 )
 
-println("Number of nodes in original instance: ", length(LabelledGraphs.vertices(ig)), "\n", " Number of nodes in clustered Hamiltonian: ", length(LabelledGraphs.vertices(cl_h)))
+println("Number of nodes in original instance: ", length(LabelledGraphs.vertices(ig)), "\n", " Number of nodes in clustered Hamiltonian: ", length(LabelledGraphs.vertices(cl_h))/2)
 ```
 
 
@@ -65,10 +76,14 @@ The Zephyr graph is a type of graph architecture used in quantum computing syste
 <img src="../images/zep.pdf" width="200%" class="center"/>
 ```
 
+In `SpinGlassPEPS.jl` solver, a grid of this type can be loaded using the command `zephyr_lattice`.
+
 ```@docs
 zephyr_lattice
 ```
 
+Below you find simple example of usage `zephyr_latttice` function.
+
 ```@example
 using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs
 
@@ -86,5 +101,5 @@ cl_h = clustered_hamiltonian(
     cluster_assignment_rule = zephyr_lattice((m, n, t))
 )
 
-println("Number of nodes in oryginal instance: ", length(LabelledGraphs.vertices(ig)), "\n", " Number of nodes in clustered Hamiltonian: ", length(LabelledGraphs.vertices(cl_h)))
+println("Number of nodes in oryginal instance: ", length(LabelledGraphs.vertices(ig)))
 ```

src/ising.jl

@@ -25,18 +25,17 @@ $(TYPEDSIGNATURES)
 
 Create an Ising graph from interaction data.
 
-This function creates an Ising graph from interaction data provided in the form of an `inst` argument.
+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.
 
 # Arguments:
 - `::Type{T}`: The type of the edge weights, typically `Float64` or `Float32`.
-- `inst::Instance`: Interaction data, which can be either a file path to a CSV file or a collection of triples `(i, j, J)`
-representing interactions between spins, where `i` and `j` are spin indices, and `J` is the interaction strength.
-- `scale::Real`: A scaling factor applied to interaction strengths (default is 1).
+- `inst::Instance`: Interaction data, which can be either a file path to a CSV file or a collection of triples `(i, j, J)` representing interactions between spins, where `i` and `j` are spin indices, and `J` is the interaction strength.
+- `scale::Real`: The scale factor establishes the convention in the Hamiltonian (default is 1).
 - `rank_override::Dict`: A dictionary specifying the rank (number of states) for each vertex. If not provided, a default rank of 2 is used for all vertices.
 
 # Returns:
-- `ig::IsingGraph{T}`: The Ising graph representing the spin system.
+- `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.

src/lattice.jl

@@ -16,7 +16,8 @@ Create a mapping from clustered Hamiltonian coordinates to a super square lattic
 Variable number of Ising graph -> Factor graph coordinate system
 
 This function generates a mapping that relates clustered Hamiltonian coordinates to a super square lattice arrangement. 
-The super square lattice is defined by the size of five dimensions: `(m, um, n, un, t)`.
+The super square lattice is defined by the size of five dimensions: `(m, um, n, un, t)`,
+where m is the number of columns, m 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)`.
@@ -39,10 +40,10 @@ $(TYPEDSIGNATURES)
 Create a mapping from clustered Hamiltonian coordinates to a simplified super square lattice arrangement.
 
 This function generates a mapping that relates clustered Hamiltonian coordinates to a simplified super square lattice arrangement. 
-The simplified super square lattice is defined by the size of three dimensions: `(m, n, t)`.
+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.
 
 # Arguments:
-- `size::NTuple{3, Int}`: A tuple specifying the size of the simplified super square lattice in three dimensions: `(m, n, t)`.
+- `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 numberr of spins in cluster.
 
 # Returns:
 - `coord_map::Dict`: A dictionary that maps clustered Hamiltonian coordinates to the corresponding lattice coordinates.
@@ -66,7 +67,7 @@ This function generates a mapping that relates clustered Hamiltonian coordinates
 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)`.
+- `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 numberr of spins in cluster. Convention: `t` is already divided by 8, so `t`=3 for Pegasus lattice.
 
 # Returns:
 - `coord_map::Dict`: A dictionary that maps clustered Hamiltonian coordinates to the corresponding Pegasus lattice coordinates.
@@ -142,7 +143,7 @@ This function generates a mapping that relates clustered Hamiltonian coordinates
 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)`.
+- `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. Convention: `t` is already divided by 4, so `t`=4 for Zephyr lattice.
 
 # Returns:
 - `coord_map::Dict`: A dictionary that maps clustered Hamiltonian coordinates to the corresponding Zephyr lattice coordinates.