Ad/docs (#20)

* add docs

* add DocStringExtensions

* fixed bug

* work in progress

* Work in Progress

* Work in Progress

* Work in progress

* somewhat done

---------

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

docs/make.jl

@@ -0,0 +1,14 @@
+using Documenter, SpinGlassEngine
+
+_pages = [
+    "Introduction" => "index.md",
+    "User Guide" => "guide.md",    
+    "API Reference" => "api.md"
+]
+# ============================
+
+makedocs(
+    sitename="SpinGlassEngine",
+    modules = [SpinGlassEngine],
+    pages = _pages
+    )

docs/src/api.md

@@ -0,0 +1,12 @@
+# Library
+
+---
+
+## Core 
+
+```@docs
+Solution
+Solution()
+low_energy_spectrum
+PEPSNetwork
+```

docs/src/guide.md

@@ -0,0 +1,43 @@
+# 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 [Chimera](https://docs.dwavesys.com/docs/latest/c_gs_4.html#chimera-graph) graph with up to 2048 spins. 
+
+
+## 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.
+
+
+```@example
+using SpinGlassEngine, SpinGlassTensors, SpinGlassNetworks, SpinGlassPEPS, MetaGraphs
+
+# Create instance and coresponding factor graph. Details can be
+# found in SpinGlassNetworks documentation.
+instance = Dict((1, 1) => 0.5, (2, 2) => 0.75, (3, 3) => -0.25, (1, 2) => -1.0, (2, 3) => 1.0)
+ig = ising_graph(instance)
+fg = factor_graph(
+        ig,
+        cluster_assignment_rule = super_square_lattice((3, 1, 1)),
+    )
+
+# Define inverse temperature for gibbs distribution used in tensor network 
+# contraction. Details can be found in SpinGlassEngine documentation
+β = 1.0
+
+# Create PEPS network
+peps = PEPSNetwork(3, 1, fg, rotation(0), β = β, bond_dim = 32)
+
+# Decide number of states we wane
+num_states = 3
+
+# Solve model
+sol = low_energy_spectrum(peps, num_states)
+@show sol.states, sol.energies
+
+```

docs/src/index.md

@@ -0,0 +1,3 @@
+# SpinGlassEngine
+
+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.

src/PEPS.jl

@@ -2,6 +2,11 @@ export PEPSNetwork, generate_boundary, node_from_index, conditional_probability
 
 const IntOrRational = Union{Int,Rational{Int}}
 
+"""
+    PEPSNetwork
+
+Structure that stores PEPS tensor network 
+"""
 struct PEPSNetwork <: AbstractGibbsNetwork{NTuple{2,Int},NTuple{2,Int}}
     factor_graph::LabelledGraph{T,NTuple{2,Int}} where {T}
     network_graph::LabelledGraph{S,NTuple{2,Int}} where {S}
@@ -21,6 +26,7 @@ struct PEPSNetwork <: AbstractGibbsNetwork{NTuple{2,Int},NTuple{2,Int}}
     layers_left_env::NTuple{K,IntOrRational} where {K}
     layers_right_env::NTuple{L,IntOrRational} where {L}
 
+
     function PEPSNetwork(
         m::Int,
         n::Int,

src/search.jl

@@ -1,6 +1,21 @@
 export AbstractGibbsNetwork,
     low_energy_spectrum, branch_state, bound_solution, merge_branches, Solution, Memoize
 
+
+"""
+Store results from branch-and-bound search.
+
+# Fields
+
+    energies::Vector{Float64}: A vector storing the energies of the system.
+    states::Vector{Vector{Int}}: A vector storing states of the system. These 
+    are states of factor graph representation of the system.
+    probabilities::Vector{Float64}: A vector storing representing the probabilities
+     of each state in the states field. Probabilities are kept as `log2`.
+    degeneracy::Vector{Int}: A vector storing the degeneracy of each energy level in the energies field.
+    largest_discarded_probability::Float64: A  value representing the largest probability that was discarded during the branch-and-bound search .
+
+"""
 struct Solution
     energies::Vector{Float64}
     states::Vector{Vector{Int}}
@@ -9,6 +24,11 @@ struct Solution
     largest_discarded_probability::Float64
 end
 
+"""
+    Solution()
+
+Creates empty `Solution`
+"""
 Solution() = Solution([0.0], [[]], [1.0], [1], -Inf)
 
 
@@ -118,6 +138,31 @@ end
 
 
 #TODO: incorporate "going back" move to improve alghoritm
+"""
+    low_energy_spectrum(
+        network::AbstractGibbsNetwork,
+        max_states::Int,
+        merge_strategy = no_merge,
+    )
+
+Search for the low-energy spectrum on a quasi-2d graph.
+
+# Details
+Compute the low energy spectrum of an Ising system represented
+by a `network` object, using a branch-and-bound search algorithm with a
+maximum number of `max_states` states and an optional `merge_strategy`.
+
+# Arguments
+- `network::AbstractGibbsNetwork`: PEPS tesnor network representing Ising system.
+- `max_states::Int`: The maximum number of states to use in the search algorithm.
+- `merge_strategy=no_merge`: An optional argument that specifies the strategy to use 
+    when merging states. The default is no_merge, which means no merging will be performed.
+
+Return value
+
+The function returns a `Solution` object representing the low energy spectrum of the system. 
+
+"""
 function low_energy_spectrum(
     network::AbstractGibbsNetwork,
     max_states::Int,

test/search_full_chimera.jl

@@ -24,7 +24,7 @@ function bench()
 
     #for transform ∈ all_lattice_transformations
     peps = PEPSNetwork(m, n, fg, rotation(0), β = β, bond_dim = 32)
-    update_gauges!(peps, :rand)
+    kupdate_gauges!(peps, :rand)
     @time sol = low_energy_spectrum(peps, num_states)#, merge_branches(peps, 1.0))
     println(sol.energies[1:1])
 end