Docs (#91)

* update ising model example

* update example in docs

* changes in intro and basic example

* start rewriting algorithm.md

* algorithm.md part2

* add more examples

* final changes

* Fixed remains of RFM in homepage and extended subpackages descriptions

* merged examples + small readability changes

* example here and in code are now identical. Few small fixes.

* additional fixes in examples

* some typos

* fix the typo in the picture

* rm TODO

---------

Co-authored-by: annamariadziubyna <[email protected]>
Co-authored-by: tomsmierz <[email protected]>

docs/make.jl

@@ -53,7 +53,8 @@ const Page = Union{Pair{String, String}, Pair{String, Vector{Pair{String, String
 _pages::Vector{Page} = [
     "Home" => "index.md",
     "Getting started" => "intro.md",
-    "Brief description of the algorithm" => "algorithm.md"
+    "Brief description of the algorithm" => "algorithm.md",
+    "More examples" => "examples.md"
 ]
 
 
@@ -123,6 +124,7 @@ end
 add_sgn_pages()
 add_sge_pages()
 add_sgt_pages()
+push!(_pages, "More examples" => "examples.md")
 # =================================
 makedocs(
     # clean = true,

docs/src/algorithm.md

@@ -1,27 +1,30 @@
 # Brief description of the algorithm
-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 [1]. Then we use approximate tensor network contraction to efficiently identify the low-energy spectrum of some quasi-two-dimensional Hamiltonians [2].
+`SpinGlassPEPS.jl` is a package developed for finding low-energy configurations in Ising type optimization problems [1, 2]. By leveraging Projected Entangled Pair States (PEPS) tensor networks, the algorithm efficiently represents the Boltzmann distribution [5], enabling heuristic exploration of quasi-2D problem spaces. In particular, this approach is tailored to tackle the challenges posed by graph geometries relevant to modern quantum annealing devices, such as the Pegasus and Zephyr graphs employed by D-Wave systems.
 
+This section builds upon the broader methodology outlined in the analysis of tensor-network limitations in solving large-scale Ising problems on Pegasus and Zephyr geometries​ [1].
+
+## Problem representation
 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$. More generally, we  mark sub-configurations of the first $k$ variables as $\underline{s}_k = (s_1, s_2, \ldots, s_k)$. Non-zero couplings $J_{ij} \in \mathbb{R}$ are input parameters of a given problem instance and form a connectivity graph $\mathcal{E}$.
 
 ## Graphs with large unit cells
-We assume that graph $\mathcal{E}$ forms a quasi-2D lattice. In real life applications such graphs have large unit cells approaching 24 spins. `SpinGlassPEPS.jl` allows for unit cells containing multiple spins. 
+We focus on the systems with quasi-2D interaction graphs, in particular those of the relevance to present-day quantum annealers, such as Pegasus and Zephyr. In the picture below, we mark group of spins which naturally form unit cells with red shapes.
 
 !!! info
     More information on lattice geometries you can find in section [Lattice Geometries](sgn/lattice.md).
 
 ```@raw html
 <img src="../images/lattice.png" width="200%" class="center"/>
 ```
-In order to adress this three types of geometries using tensor networks, we represent the problem as a Potts Hamiltonian. To that end we group together sets of variables. In this framework Ising problem translates to:
+In order to adress graph geometries with large unit cells using tensor networks, we represent the problem as a Potts Hamiltonian. To that end we group together sets of binary variables into clusters with a reduced number of variables of larger dimensions. In this framework Ising problem translates to:
 ```math
 H(\underline{x}_{\bar{N}}) = \sum_{\langle m,n\rangle \in \mathcal{F}} E_{x_m x_n} + \sum_{n=1}^{\bar{N}} E_{x_n}
 ```
 where $\mathcal{F}$ forms a 2D graph, in which we indicate nearest-neighbour interactions with blue lines, and diagonal connections with green lines in the picture above.
-Each $x_n$ takes $d$ values with  $d=2^4$ for square diagonal, $d=2^{24}$ for Pegasus and $2^{16}$ for Zephyr geometry. 
+In this example, $x_n$ takes $d$ values with  $d=2^4$ for square diagonal, $d=2^{24}$ for Pegasus and $2^{16}$ for Zephyr geometry (in the maximal case when all qubits are operational). 
 $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/clustering.png" width="200%" class="center"/>
@@ -45,7 +48,10 @@ By employing branch and bound search strategy iteratively row after row, we addr
 <img src="../images/bb.png" width="200%" class="center"/>
 ```
 ## Tensor network contractions for optimization problems
-Branch and bound search relies on the calculation of conditional probabilities. To that end, we use tensor network techniques. 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.
+Branch and bound search relies on the calculation of conditional probabilities. To that end, we use tensor network techniques. Conditional probabilities are obtained by contracting a PEPS tensor network, which, although an NP-hard problem, can be computed approximately. The approach utilized in `SpinGlassPEPS.jl` is boundary matrix product state (MPS) illustrated in the figure below. Tensors in the pink box are approximated by matrix product state with truncated bond dimension. In each step, a product of boundary MPS from the previous row and the matrix product operator (MPO) formed by the next row of tensors, is approximated by a new boundary MPS of limited bond dimension. 
+
+!!! info
+    In `SpinGlassPEPS.jl` one can use two types of approximating boundary MPS. More information you can find in the section [Search parameters](sge/params.md).
 
 ```@raw html
 <img src="../images/prob.png" width="150%" class="center"/>
@@ -56,8 +62,12 @@ Branch and bound search relies on the calculation of conditional probabilities.
 
 ## References & Related works
 
-1. "Two-Dimensional Tensor Product Variational Formulation" T. Nishino, Y. Hieida, K. Okunishi, N. Maeshima, Y. Akutsu, A. Gendiar, [Progr. Theor. Phys. 105, 409 (2001)](https://academic.oup.com/ptp/article/105/3/409/1834124)
+1. "Limitations of tensor network approaches for optimization and sampling: A comparison against quantum and classical Ising machines" A.M. Dziubyna, T. Śmierzchalski, B. Gardas, M.M. Rams, M. Mohseni [arXiv:2411.16431] (https://arxiv.org/abs/2411.16431)
+
+2. "SpinGlassPEPS.jl: low-energy solutions for near-term quantum annealers" T. Śmierzchalski, A.M. Dziubyna, K. Jałowiecki, Z. Mzaouali, Ł. Pawela, B. Gardas, M.M. Rams []
+
+3. "Approximate optimization, sampling, and spin-glass droplet discovery with tensor networks" Marek M. Rams, Masoud Mohseni, Daniel Eppens, Konrad Jałowiecki, Bartłomiej Gardas [Phys. Rev. E 104, 025308 (2021)](https://journals.aps.org/pre/abstract/10.1103/PhysRevE.104.025308) or arXiv version [arXiv:1811.06518](https://arxiv.org/abs/1811.06518)
 
-2. "Approximate optimization, sampling, and spin-glass droplet discovery with tensor networks" Marek M. Rams, Masoud Mohseni, Daniel Eppens, Konrad Jałowiecki, Bartłomiej Gardas [Phys. Rev. E 104, 025308 (2021)](https://journals.aps.org/pre/abstract/10.1103/PhysRevE.104.025308) or arXiv version [arXiv:1811.06518](https://arxiv.org/abs/1811.06518)
+4. [tnac4o](https://github.com/marekrams/tnac4o/tree/master)
 
-3. [tnac4o](https://github.com/marekrams/tnac4o/tree/master)
+5. "Two-Dimensional Tensor Product Variational Formulation" T. Nishino, Y. Hieida, K. Okunishi, N. Maeshima, Y. Akutsu, A. Gendiar, [Progr. Theor. Phys. 105, 409 (2001)](https://academic.oup.com/ptp/article/105/3/409/1834124)

docs/src/examples.md

@@ -0,0 +1,97 @@
+# More examples
+In this section, we present a few examples demonstrating the functionality of `SpinGlassPEPS.jl`. These examples showcase how to construct tensor networks, work with Potts Hamiltonians, and perform branch and bound search for optimization problems.
+
+The full list of examples, including detailed code and visualizations, can be found on the [GitHub](https://github.com/euro-hpc-pl/SpinGlassPEPS.jl/tree/master/examples).
+
+## Inpainting
+This example demonstrates how to solve an [inpainting](https://en.wikipedia.org/wiki/Inpainting) problem  using `SpinGlassPEPS.jl`. 
+
+```@julia
+using SpinGlassPEPS
+
+function bench_inpaining(::Type{T}, β::Real, max_states::Integer, bond_dim::Integer) where {T}
+	potts_h= potts_hamiltonian(instance, 120, 120)
+
+	params = MpsParameters{T}(; bond_dim = bond_dim, method = :svd)
+	search_params = SearchParameters(; max_states = max_states)
+	net = PEPSNetwork{SquareSingleNode{GaugesEnergy}, Sparse, T}(120, 120, potts_h, rotation(0))
+	ctr = MpsContractor{SVDTruncate, NoUpdate, T}(net, params; onGPU = true, beta = convert(Float64, β), graduate_truncation = true)
+    droplets = SingleLayerDroplets(; max_energy = 100, min_size = 100 , metric = :hamming, mode=:RMF)
+	merge_strategy = merge_branches(ctr; merge_prob = :none, droplets_encoding = droplets)
+
+	sol, info = low_energy_spectrum(ctr, search_params, merge_strategy)
+    ground = sol.energies[begin]
+
+    println("Best energy found: $(ground)")
+    sol
+end
+sol = bench_inpaining(Float64, 6, 64, 4)
+```
+### Key steps
+* The function `potts_hamiltonian` generates a Hamiltonian for a 120x120 grid.
+* A PEPS tensor network is initialized with the RMF instance, using `Sparse` tensors and a `SquareSingleNode` representation.
+* The contraction is performed using parameters saved in `MpsContractor`. We use `SVDTruncate` to optimize boundary MPSs. The `onGPU` flag enables GPU acceleration.
+* The function `low_energy_spectrum` searches for low-energy configurations with branch merging and droplet search.
+
+!!! info "Data visualisation"
+    To fully interpret the results, the data might be visualized. This example generates raw data, but a full visualization guide is available on [GitHub](https://github.com/euro-hpc-pl/SpinGlassPEPS.jl/blob/master/examples/inpaining.jl)
+
+## D-Wave Pegasus
+This example demonstrates how to perform an optimization on the Pegasus lattice with 216 spins using `SpinGlassPEPS.jl`. It is a computationally demanding example that involves truncating cluster states from 2^24 to the 2^16  most probable states. The example requires GPU support for efficient computation and may take several minutes to complete.
+
+```@julia
+using SpinGlassPEPS
+
+function run_pegasus_bench(::Type{T}; topology::NTuple{3, Int}) where {T}
+    m, n, t = topology
+    instance = "$(@__DIR__)/instances/P4_CBFM-P.txt"
+    results_folder = "$(@__DIR__)/lbp"
+    isdir(results_folder) || mkdir(results_folder)
+
+    lattice = pegasus_lattice(topology)
+
+    potts_h = potts_hamiltonian(
+        ising_graph(instance),
+        spectrum = full_spectrum,
+        cluster_assignment_rule = lattice,
+    )
+
+    potts_h = truncate_potts_hamiltonian(potts_h, T(2), 2^16, results_folder, "P4_CBFM-P"; tol=1e-6, iter=2)
+
+    params = MpsParameters{T}(bond_dim=16, num_sweeps=1)
+    search_params = SearchParameters(max_states=2^8, cutoff_prob=1e-4)
+
+    best_energies = T[]
+
+    for transform in all_lattice_transformations
+        net = PEPSNetwork{SquareCrossDoubleNode{GaugesEnergy}, Sparse, T}(m, n, potts_h, transform)
+        ctr = MpsContractor(Zipper, net, params; onGPU=true, beta=T(2), graduate_truncation=true)
+
+        droplets = SingleLayerDroplets(max_energy=10, min_size=54, metric=:hamming)
+        merge_strategy = merge_branches(ctr; merge_prob=:none, droplets_encoding=droplets)
+
+        sol, _ = low_energy_spectrum(ctr, search_params, merge_strategy)
+        sol2 = unpack_droplets(sol, T(2))
+
+        println("Droplet energies: $(sol2.energies)")
+
+        push!(best_energies, sol.energies[1])
+        clear_memoize_cache()
+    end
+
+    ground = best_energies[1]
+    @assert all(ground .≈ best_energies)
+    println("Best energy found: $(best_energies[1])")
+end
+
+T = Float64
+@time run_pegasus_bench(T; topology = (3, 3, 3))
+```
+
+### Key steps
+* The Potts Hamiltonian is constructed from an Ising graph build based on the input file (`P4_CBFM-P.txt`).
+* The Hamiltonian is then truncated using a truncate_potts_hamiltonian function, keeping only the most probable states, with the number of states in every cluster reduced from 2^24 to 2^16 . This truncation significantly reduces the numerical cost of the subsequent tensor network contraction. Note that, this is optional step.
+* A PEPS (Projected Entangled Pair States) network is created with a `SquareCrossDoubleNode` and `GaugesEnergy` for representing the system on the lattice. 
+* Structures such as `MpsParameters` and  `SearchParameters` stores the information about e.g. a predefined bond dimension and a number of states considered during the search.
+* `MpsContractor` stores information needed in subsequent tensor network contraction. The contraction is performed using a `Zipper` method for optimizing boundary MPS. 
+* The function `low_energy_spectrum` searches for low-energy configurations with branch merging and droplet search. We are searching for droplets with an energy `max_energy` higher than the ground state by at most 10, and the minimal size `min_size` of 54.

docs/src/index.md

@@ -4,7 +4,7 @@ Author = "Tomasz Śmierzchalski, Anna M. Dziubyna, Konrad Jałowiecki, Zakaria M
 
 # Welcome to SpinGlassPEPS.jl documentation!
 
-Welcome to `SpinGlassPEPS.jl`, a 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.
+Welcome to `SpinGlassPEPS.jl`, a open-source Julia package designed for heuristically solving Ising-type optimization problems defined on quasi-2D lattices.
 
 !!! 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.
@@ -13,32 +13,54 @@ Welcome to `SpinGlassPEPS.jl`, a open-source Julia package designed for heuristi
 ## Overview
 In this section we will provide a condensed overview of the package.
 
-`SpinGlassPEPS.jl` is a collection of Julia packages bundled together under a single package `SpinGlassPEPS.jl`. It can be installed using the Julia package manager for Julia v1.6 and higher. Inside the Julia REPL, type ] to enter the Pkg REPL mode and then run
+`SpinGlassPEPS.jl` is a collection of Julia packages bundled together under a single package `SpinGlassPEPS.jl`. It can be installed using the Julia package manager for Julia v1.10. Inside the Julia REPL, type ] to enter the Pkg REPL mode and then run
 ```julia
 using Pkg; 
 Pkg.add("SpinGlassPEPS")
 ```
-The package `SpinGlassPEPS.jl` includes:
-* `SpinGlassEngine.jl` - Package containing the solver itself and tools focused on finding and operating on excitations. 
-* `SpinGlassNetworks.jl` - Package containing all tools needed to construct an Ising graph from a given instance and create Potts Hamiltonian.
-* `SpinGlassTensors.jl` - Package containing all necessary functionalities for creating and operating on tensors. It allows the use of both CPU and GPU.
+The package `SpinGlassPEPS.jl` includes three independent sub-packages:
+* `SpinGlassEngine.jl` -  serves as the core package, consisting of routines for executing the branch-and-bound method (with the ability to leverage the problem's locality) for a given Potts instance. It also includes capabilities for reconstructing the low-energy spectrum from identified localized excitations and provides a tensor network constructor. 
+* `SpinGlassNetworks.jl` - facilitates the generation of an Ising graph from a given instance using a set of standard inputs (e.g., instances compatible with the Ocean environment provided by D-Wave) and supports clustering to create effective Potts Hamiltonians.
+* `SpinGlassTensors.jl` - offers essential tools for creating and manipulating tensors that constitute the PEPS network, with support for both CPU and GPU utilization. It manages core operations on tensor networks, including contraction, using the boundary Matrix Product State approach. This package primarily functions as a backend, and users generally do not interact with it directly.
 
 ```@raw html
 <img src="images/algorithm.png" width="200%" class="center"/>
 ```
 
 ## Our goals
 
-`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 to identify the most probable states according to the Gibbs distribution. `SpinGlassPEPS.jl` is a 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 retains the largest discarded probability during the branch and bound optimization procedure. Notably, `SpinGlassPEPS.jl` goes beyond ground states, introducing a feature for identifying and analyzing spin glass droplets — collective excitations crucial for understanding system dynamics beyond the fundamental ground state configurations. 
+`SpinGlassPEPS.jl` was created to heuristically solve Ising-type optimization problems defined on quasi-2D lattices. This package combines advanced heuristics to address optimization challenges and employs tensor network contractions to compute conditional probabilities to identify the most probable states according to the Gibbs distribution. `SpinGlassPEPS.jl` is a tool for reconstructing the low-energy spectrum of Ising spin glass Hamiltonians and some more general Potts Hamiltonians. Beyond energy computations, the package offers insights into spin configurations, associated probabilities, and retains the largest discarded probability during the branch and bound optimization procedure. Notably, `SpinGlassPEPS.jl` goes beyond ground states, introducing a feature for reconstructing the low-energy spectrum from identified localized excitations in the system, called spin-glass droplets.
 ```@raw html
 <img src="images/result.png" width="200%" class="center"/>
 ```
 
 ## Citing SpinGlassPEPS.jl
-If you use `SpinGlassPEPS.jl` for academic research and wish to cite it, please use the following paper:
+If you use `SpinGlassPEPS.jl` for academic research and wish to cite it, please use the following papers:
+
+* Article describing this package and code.
+```
+@article{SpinGlassPEPS.jl,
+    author = {Tomasz \'{S}mierzchalski and Anna Maria Dziubyna and Konrad Ja\l{}owiecki and Zakaria
+    Mzaouali and {\L}ukasz Pawela and Bart\l{}omiej Gardas and Marek M. Rams},
+    title = {{SpinGlassPEPS.jl}: low-energy solutions for near-term quantum annealers},
+    journal = {},
+    year = {},
+}
+```
+
+* Article describing in details used algorithms and containing extensive benchmarks.
+```
+@misc{SpinGlassPEPS, 
+    author = {Anna Maria Dziubyna and Tomasz \'{S}mierzchalski and Bart\l{}omiej Gardas and Marek M. Rams and Masoud Mohseni},
+    title = {Limitations of tensor network approaches for optimization and sampling: A comparison against quantum and classical {Ising} machines},
+    year = {2024},
+    eprint={2411.16431},
+    archivePrefix={arXiv},
+    primaryClass={cond-mat.dis-nn},
+    doi = {10.48550/arXiv.2411.16431} 
+}
+```
 
-Tomasz Śmierzchalski, Anna M. Dziubyna, Konrad Jałowiecki, Zakaria Mzaouali, Łukasz Pawela, Bartłomiej Gardas and Marek M. Rams, 
-*“SpinGlassPEPS.jl: low-energy solutions for near-term quantum annealers"*
 
 ## Contributing
 Contributions are always welcome: