add the docs

docs/make.jl

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

docs/src/api.md

@@ -8,7 +8,6 @@ CurrentModule = SpinGlassNetworks
 
 ## Ising Graphs
 ```@docs
-ising_graph
 inter_cluster_edges
 prune
 couplings
@@ -17,7 +16,6 @@ couplings
 ## Clustered Hamiltonian
 ```@docs
 split_into_clusters
-clustered_hamiltonian
 decode_clustered_hamiltonian_state
 rank_reveal
 energy
@@ -28,22 +26,13 @@ exact_cond_prob
 truncate_clustered_hamiltonian
 ```
 
-## Lattice
-```@docs
-super_square_lattice
-pegasus_lattice
-zephyr_lattice
-```
-
 ## Belief propagation
 ```@docs
 local_energy
 interaction_energy
 get_neighbors
-belief_propagation
 MergedEnergy
 update_message
-clustered_hamiltonian_2site
 merge_vertices_cl_h
 projector
 SparseCSC
@@ -68,7 +57,6 @@ brute_force
 ## Truncate
 ```@docs
 truncate_clustered_hamiltonian_1site_BP
-truncate_clustered_hamiltonian_2site_BP
 truncate_clustered_hamiltonian_2site_energy
 select_numstate_best
 ```

docs/src/bp.md

@@ -0,0 +1,9 @@
+## Belief propagation
+
+Local dimensional reduction can be achieved by selectively choosing states in the clustered Hamiltonian that have the lowest local energy in the cluster. This approach aims to reduce the dimensionality of the problem by focusing on the most relevant and energetically favorable states. It can be done by truncation based on energy or truncation based on Loopy Belief Propagation.
+
+```@docs
+clustered_hamiltonian_2site
+belief_propagation
+truncate_clustered_hamiltonian_2site_BP
+```

docs/src/clh.md

@@ -0,0 +1,25 @@
+# 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.
+
+```@docs
+clustered_hamiltonian
+```
+
+## Simple example
+
+```@example
+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)
+ig = ising_graph(instance)
+
+# Create clustered Hamiltonian.
+cl_h = clustered_hamiltonian(
+    ig,
+    cluster_assignment_rule = super_square_lattice((3, 1, 1))
+)
+```

docs/src/ising.md

@@ -0,0 +1,25 @@
+# Introduction
+
+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.
+
+```@docs
+ising_graph
+```
+
+## Simple example
+```@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
+ig = ising_graph(instance)
+
+# View graph properties
+@show biases(ig), couplings(ig)
+```

docs/src/lattice.md

@@ -0,0 +1,90 @@
+## Lattice
+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.
+
+```@docs
+super_square_lattice
+```
+
+```@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
+
+cl_h = clustered_hamiltonian(
+    ig,
+    cluster_assignment_rule = super_square_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)))
+```
+
+## Pegasus graphs
+The Pegasus graph is a type of graph architecture used in quantum computing systems, particularly in the quantum annealing machines developed by D-Wave Systems. It is designed to provide a grid of qubits with specific connectivity patterns optimized for solving certain optimization problems. Futer details can be found [here](https://docs.dwavesys.com/docs/latest/c_gs_4.html#pegasus-graph).
+```@raw html
+<img src="../images/peg.pdf" width="200%" class="center"/>
+```
+
+```@docs
+pegasus_lattice
+```
+
+```@example
+using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs
+
+# load Chimera instance and create Ising graph
+instance = "$(@__DIR__)/../../src/instances/pegasus_random/P4/RAU/001_sg.txt"
+ig = ising_graph(instance)
+
+# Loaded instance is pegasus graph
+m = 3
+n = 3
+t = 3
+
+cl_h = clustered_hamiltonian(
+    ig,
+    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)))
+```
+
+
+## Zephyr graphs
+The Zephyr graph is a type of graph architecture used in quantum computing systems, particularly in the quantum annealing machines developed by D-Wave Systems. Futer details can be found [here](https://docs.dwavesys.com/docs/latest/c_gs_4.html#zephyr-graph).
+```@raw html
+<img src="../images/zep.pdf" width="200%" class="center"/>
+```
+
+```@docs
+zephyr_lattice
+```
+
+```@example
+using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs
+
+# load Chimera instance and create Ising graph
+instance = "$(@__DIR__)/../../src/instances/zephyr_random/Z3/RAU/001_sg.txt"
+ig = ising_graph(instance)
+
+# Loaded instance is zephyr graph
+m = 6
+n = 6
+t = 4
+
+cl_h = clustered_hamiltonian(
+    ig,
+    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)))
+```

docs/src/userguide.md

@@ -1,125 +1,5 @@
 # Introduction
-This section provides examples of how to use the 'ising_graph' function to generate an Ising model graph and the 'clustered_hamiltonian' function to convert the Ising graph into a clustered Hamiltonian.
 
-# Ising Graph
-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:
+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.
 
-$$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.
-
-
-## Simple example
-```@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
-ig = ising_graph(instance)
-
-# View graph properties
-@show biases(ig), couplings(ig)
-```
-
-## Generalisation
-
-The 'ising_graph' function is quite general function. One can easly convert instance into another hamiltonian convention, ex.
-```math
-H = - \sum_{(i,j) \in \mathcal{E}} J_{ij} s_i s_j - \mu \sum_{i} h_i s_i
-```
-
-'ising_graph' also allows for building other spin system, not only spin-``\frac{1}{2}`` system. For example one may build chain where sites allows for 3 spin values.
-
-```@example
-using SpinGlassNetworks
-
-# Create spin chain instance 
-instance = Dict((1, 1) => 1.0, (2, 2) => 0.5, (3, 3) => -0.25, 
-(1, 2) => -1.0, (2, 3) => 1.0)
-
-rank_override = Dict(1 => 3, 2 => 3, 3 => 3)
-
-sg = ising_graph(instance, rank_override=rank_override)
-
-# see ranks of each site
-rank_vec(sg)
-```
-
-# Clustered Hamiltonian
-
-A clustered Hamiltonian is a graphical representation that allows for a convenient and intuitive way to describe the structure of a tensor network.
-
-A clustered Hamiltonian consists of two types of nodes: variable nodes and factor nodes. Variable nodes represent the tensors in the tensor network, and factor nodes represent the operations that are applied to those tensors.
-
-Each variable node in the clustered Hamiltonian corresponds to a tensor in the tensor network, and each factor node corresponds to a tensor contraction or operation that is applied to one or more of those tensors. The edges between the nodes in the clustered Hamiltonian represent the indices that are shared between the corresponding tensors in the tensor network.
-
-## Simple example
-
-```@example
-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)
-ig = ising_graph(instance)
-
-# Create clustered Hamiltonian.
-cl_h = clustered_hamiltonian(
-    ig,
-    cluster_assignment_rule = super_square_lattice((3, 1, 1))
-)
-```
-
-## Pegasus graphs
-The Pegasus graph is a type of graph architecture used in quantum computing systems, particularly in the quantum annealing machines developed by D-Wave Systems. It is designed to provide a grid of qubits with specific connectivity patterns optimized for solving certain optimization problems. Futer details can be found [here](https://docs.dwavesys.com/docs/latest/c_gs_4.html#pegasus-graph).
-```@raw html
-<img src="../images/peg.pdf" width="200%" class="center"/>
-```
-
-```@example
-using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs
-
-# load Chimera instance and create Ising graph
-instance = "$(@__DIR__)/../../src/instances/pegasus_random/P4/RAU/001_sg.txt"
-ig = ising_graph(instance)
-
-# Loaded instance is pegasus graph
-m = 3
-n = 3
-t = 3
-
-cl_h = clustered_hamiltonian(
-    ig,
-    cluster_assignment_rule = pegasus_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)))
-```
-
-
-## Zephyr graphs
-The Zephyr graph is a type of graph architecture used in quantum computing systems, particularly in the quantum annealing machines developed by D-Wave Systems. Futer details can be found [here](https://docs.dwavesys.com/docs/latest/c_gs_4.html#zephyr-graph).
-```@raw html
-<img src="../images/zep.pdf" width="200%" class="center"/>
-```
-```@example
-using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs
-
-# load Chimera instance and create Ising graph
-instance = "$(@__DIR__)/../../src/instances/zephyr_random/Z3/RAU/001_sg.txt"
-ig = ising_graph(instance)
-
-# Loaded instance is zephyr graph
-m = 6
-n = 6
-t = 4
-
-cl_h = clustered_hamiltonian(
-    ig,
-    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)))
-```
+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.