add the docs

docs/src/examples.md

@@ -326,6 +326,6 @@ ctr = MpsContractor{Strategy, Gauge}(net, [β/6, β/3, β/2, β], :graduate_trun
 ```
 
 # Random Markov Field optimization problems
-Random Markov Field type model on a 2d squarre lattice with cost function
+Random Markov Field type model on a 2D square lattice with cost function
 $$H =  \sum_{(i,j) \in \mathcal{E}} E(s_i, s_j) + \sum_{i} E(s_i)$$
 and nearest-neighbour interactions only.

docs/src/index.md

@@ -5,7 +5,6 @@ Author = "Krzysztof Domino, Bartłomiej Gardas, Konrad Jałowiecki, Łukasz Pawe
 # Welcome to SpinGlassPEPS documentation!
 
 Welcome to `SpinGlassPEPS.jl`, a powerful open-source Julia package designed for heuristically solving Ising-type optimization problems defined on quasi-2D lattices and Random Markov Fields on 2D rectangular lattices.
-<!-- `SpinGlassPEPS` is an open-source Julia package for numerical computation in quantum information theory.  -->
 
 !!! info "Star us on GitHub!" 
     If you have found this library useful, please consider starring the GitHub repository. This gives us an accurate lower bound of the satisfied users.
@@ -29,7 +28,6 @@ The package `SpinGlassPEPS` includes:
 
 `SpinGlassPEPS.jl` was created to heuristically solve Ising-type optimization problems defined on quasi-2D lattices or Random Markov Fields (RMF) on 2D rectangular lattices. This package combines advanced heuristics to address optimization challenges and employs tensor network contractions to compute conditional probabilities and identify the most probable states according to the Gibbs distribution. `SpinGlassPEPS.jl` is a versatile tool for reconstructing the low-energy spectrum of Ising spin glass Hamiltonians and RMF Hamiltonians. Beyond energy computations, the package offers insights into spin configurations, associated probabilities, and even retains the largest discarded probability during the branch and bound optimization procedure. Notably, `SpinGlassPEPS.jl` goes beyond ground states, introducing a unique feature for identifying and analyzing spin glass droplets — collective excitations crucial for understanding system dynamics beyond the fundamental ground state configurations. 
 
-<!-- We aim to provide fast, reliable and easy to use emulator of D-Wave ``2000``Q quantum annealers. Our solver calculates ``L \ll 2 ^N`` low energy states (and their corresponding energies) for ``N \le 2048``.  -->
 
 ## Citing SpinGlassPEPS
 If you use `SpinGlassPEPS` for academic research and wish to cite it, please use the following paper:

docs/src/intro.md

@@ -2,19 +2,26 @@
 Before providing the documentation of the offered functionality, it is good to demonstrate exactly what the package does.
 
 ## Introduction
-We consider tensor network based algorithm for finding ground state configurations of quasi-2D Ising problems. We employ tensor networks to represent the Gibbs distribution. Then we use approximate tensor network contraction to efficiently identify the low-energy spectrum of some quasi-two-dimensional Hamiltonians.
+We consider tensor network based algorithm for finding ground state configurations of quasi-2D problems. We employ tensor networks to represent the Gibbs distribution. Then we use approximate tensor network contraction to efficiently identify the low-energy spectrum of some quasi-two-dimensional Hamiltonians.
 
+### Ising spin glass problems
 Let us consider a classical Ising Hamiltonian
 ```math
 H(\underline{s}_N) =  \sum_{\langle i, j\rangle \in \mathcal{E}} J_{ij} s_i s_j + \sum_{i =1}^N J_{ii} s_i,
 ```
 where ``\underline{s}_N`` denotes a particular configuration of ``N`` binary variables ``s_i=\pm 1``. Non-zero couplings ``J_{ij} \in \mathbb{R}`` are input parameters of a given problem instance and form a connectivity graph ``\mathcal{E}``.
 
-Inspired by near-term quantum annealers, we assume that graph ``\mathcal{E}`` forms a quasi-2D lattice — in particular on a [Pegasus](https://docs.dwavesys.com/docs/latest/c_gs_4.html#pegasus-graph) and [Zephyr](https://docs.dwavesys.com/docs/latest/c_gs_4.html#zephyr-graph) graphs (D-Wave). Unit cells for Pegasus and Zephyr graphs consist of 24 and 16 spins respectively.
+Inspired by near-term quantum annealers, we assume that graph ``\mathcal{E}`` forms a quasi-2D lattice — in particular on a [Pegasus](https://docs.dwavesys.com/docs/latest/c_gs_4.html#pegasus-graph) and [Zephyr](https://docs.dwavesys.com/docs/latest/c_gs_4.html#zephyr-graph) graphs (D-Wave). Unit cells for Pegasus and Zephyr graphs consist of 24 and 16 spins respectively. Our solver is, however, more generall than D-Wave graphs. It can search for solutions of problems on square diagonal lattices. 
+
+`SpinGlassPEPS.jl` translates the problem into a tensor network language, and performing branch and bound search, finds the low energy spectrum of a given problem.
 
 ```@raw html
-<img src="../images/graphs.pdf" width="200%" class="center"/>
+<img src="../images/peps_graph.pdf" width="200%" class="center"/>
 ```
+### Random Markov Fields
+Random Markov Field type model on a 2D square lattice with cost function
+$$H =  \sum_{(i,j) \in \mathcal{E}} E(s_i, s_j) + \sum_{i} E(s_i)$$
+and nearest-neighbour interactions only.
 
 ## Branch and bound search
 By employing branch and bound search strategy iteratively row after row, we address the solution of Hamiltonian in the terms of conditional probabilities. This approach enables the identification of most probable (low-energy) spin configurations within the problem space. 
@@ -25,16 +32,8 @@ By employing branch and bound search strategy iteratively row after row, we addr
 
 ## Calculating conditional probabilities
 
-```@raw html
-<img src="../images/prob.pdf" width="150%" class="center"/>
-```
+In order to indentify most probable states we need to calculate the conditional probabilities. Conditional probabilities are obtained by contracting a PEPS tensor network, which, although an NP-hard problem, can be computed approximately. The approach utilized is boundary MPS-MPO, which involves contracting a tensor network row by row and truncating the bond dimension.
 
 ```@raw html
-<img src="../images/PEPS.pdf" width="120%" class="center"/>
-```
-
-
-## Finding structure of low energy states
-Below we describe simple Ising chain spin system with open boundary condition. The system has three spins with couplings ``J_{12} = -1.0`` and``J_{23} = 1.0``. Additionaly there are local fields ``h_1 = 0.5``, ``h_2 = 0.75`` and ``h_3 = -0.25``. 
-
-We can calculate spectrum using `SpinGlassPEPS`. First we create graph (called Ising graph) which corespond to given Ising system. Then from this graph we create PEPS tensor network. Lastly we define model's parameters and control parameters such as `num_states` - maximal number of low energy states to be found. Then we can use function `low_energy_spectrum` to find desired low energy spectrum.
+<img src="../images/prob.pdf" width="150%" class="center"/>
+```

docs/src/sge/guide.md

@@ -1,12 +1,5 @@
 # Introduction
-We consider a classical Ising Hamiltonian
-```math
-E = \sum_{<i,j> \in \mathcal{E}} J_{ij} s_i s_j + \sum_j h_i s_j.
-```
-where ``s`` is a configuration of ``N`` classical spins taking values ``s_i = \pm 1``
-and ``J_{ij}, h_i \in \mathbb{R}`` are input parameters of a given problem instance. 
-Nonzero couplings ``J_{ij}`` form a graph ``\mathcal{E}``. Edges of ``\mathcal{E}`` form a quasi-two-dimensional structure. In this package we focus in particular on the [Pegasus](https://docs.dwavesys.com/docs/latest/c_gs_4.html#pegasus-graph) and [Zephyr](https://docs.dwavesys.com/docs/latest/c_gs_4.html#zephyr-graph) graphs.
+A [Julia](http://julialang.org) package for finding low energy spectrum of Ising spin systems. Part of [SpinGlassPEPS](https://github.com/euro-hpc-pl/SpinGlassPEPS.jl) package.
 
-
-## Finding structure of low energy states
+This part of the documentation is dedicated to describing the `SpinGlassEngine.jl` package, which serves as the actual solver. First, we will demonstrate how to construct a tensor network using the clustered Hamiltonian obtained with the `SpinGlassNetworks.jl` package. Next, we discuss the parameters necessary for conducting calculations, which the user should provide. Finally, we present functions that enable the discovery of low-energy spectra.
 

docs/src/sge/params.md

@@ -1,4 +1,15 @@
-# Structures to store parameters
+# Contracting PEPS tensor network
+Once we construct the tensor network, we can proceed with its contraction. The first step involves preparing structures to store information about the approximate contraction using the MPS-MPO method and the exploration of states through the branch-and-bound algorithm.
+
+```@raw html
+<img src="../images/contract.pdf" width="200%" class="center"/>
+```
+
+```@docs
+MpsContractor
+```
+
+# Structures to store parameters used in branch and bound search
 ```@docs
 MpsParameters
 SearchParameters
@@ -17,9 +28,9 @@ These approaches provide users with distinct strategies to efficiently contract
 
 # Sparsity 
 In the domain of matrix operations, our package recognizes the significance of two primary approaches: 
-* `dense` 
-* `sparse`. 
-The latter, referred to as sparsity, plays a pivotal role in various computational contexts. Frequently, the matrices involved in our calculations exhibit sparse characteristics, wherein a significant portion of their elements is zero. To accommodate this, our package offers the flexibility to choose the `sparse` mode. This option not only optimizes memory usage but also substantially enhances computational efficiency, particularly when dealing with matrices characterized by a scarcity of non-zero entries. By selecting the sparse mode, users can leverage the inherent structure of these matrices, streamlining computations, and expediting solutions for intricate problems. This feature underscores our commitment to providing users with the tools to tailor their computational strategies based on the nature of the matrices involved, ensuring optimal performance across diverse scenarios.
+* `Dense` 
+* `Sparse`. 
+The latter, referred to as sparsity, plays a pivotal role in various computational contexts. Frequently, the matrices involved in our calculations exhibit sparse characteristics, wherein a significant portion of their elements is zero. To accommodate this, our package offers the flexibility to choose the `Sparse` mode. This option not only optimizes memory usage but also substantially enhances computational efficiency, particularly when dealing with matrices characterized by a scarcity of non-zero entries. By selecting the sparse mode, users can leverage the inherent structure of these matrices, streamlining computations, and expediting solutions for intricate problems. This feature underscores our commitment to providing users with the tools to tailor their computational strategies based on the nature of the matrices involved, ensuring optimal performance across diverse scenarios.
 
 # Layout 
 Different decompositions of the network into MPS:

docs/src/sge/peps.md

@@ -1,5 +1,6 @@
-# Constructing tensor network
+# Constructing PEPS tensor network
 
+After creating the clustered Hamiltonian, a visual guide to the problem's structure, we can turn it into a PEPS tensor network as shown in the figure below. In all lattices we supporrt, the essential components resembling unit cells are represented by red circles and described using the formula $\underset{x_m}{\Tr} (\exp{(-\beta E_{x_m})} P^{ml}P^{mr}P^{mu}P^{md})$. Here, $x_m$ refers to a group of spins within the cluster in focus, while $P_{ml}, P_{mr}, \ldots$ denote subsets of spins within $x_m$ interacting with neighboring clusters in various directions like left and right. Spins in adjacent clusters influence each other, depicted by blue squares. Additionally, we permit diagonal interactions between next nearest neighbors, facilitated by green squares.
 
 ```@raw html
 <img src="../images/peps.pdf" width="200%" class="center"/>
@@ -9,10 +10,37 @@
 PEPSNetwork
 ```
 
-```@raw html
-<img src="../images/contract.pdf" width="200%" class="center"/>
-```
 
-```@docs
-MpsContractor
-```
+```@example
+using SpinGlassEngine, SpinGlassTensors, SpinGlassNetworks, SpinGlassPEPS
+using SpinGlassExhaustive
+using Logging
+using LightGraphs
+using LinearAlgebra
+using TensorCast
+using MetaGraphs
+using Statistics
+
+function my_brute_force(ig::IsingGraph; num_states::Int)
+    brute_force(ig, onGPU ? :GPU : :CPU, num_states=num_states)
+end
+
+function bench(instance::String)
+    m, n, t = 5, 5, 4
+    onGPU = true
+
+    ig = ising_graph(instance)
+    cl_h = clustered_hamiltonian(
+        ig,
+        spectrum = full_spectrum,
+        cluster_assignment_rule=super_square_lattice((m, n, t))
+    )
+    for Strategy ∈ (SVDTruncate, MPSAnnealing, Zipper), transform ∈ all_lattice_transformations
+        for Layout ∈ (GaugesEnergy, EnergyGauges, EngGaugesEng), Sparsity ∈ (Dense, Sparse)
+            net = PEPSNetwork{SquareCrossSingleNode{Layout}, Sparsity}(m, n, cl_h, transform)
+        end
+    end
+end
+
+bench("$(@__DIR__)/../src/instances/square_diagonal/5x5/diagonal.txt")
+```

docs/src/sgn/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/sgn/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/sgn/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)))
 ```