Docs (#16)

* new docs

* add automatic onGPU in tests

* version changed

* docs remove API

* add onGPU

---------

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

Project.toml

@@ -1,7 +1,7 @@
 name = "SpinGlassNetworks"
 uuid = "b7f6bd3e-55dc-4da6-96a9-ef9dbec6ac19"
 authors = ["Anna Maria Dziubyna <[email protected]>", "Tomasz Śmierzchalski <[email protected]>", "Bartłomiej Gardas <[email protected]>", "Konrad Jałowiecki <[email protected]>", "Łukasz Pawela <[email protected]>", "Marek M. Rams <[email protected]>"]
-version = "1.2.0"
+version = "1.3.0"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
@@ -28,7 +28,7 @@ LabelledGraphs = "0.4.4"
 MKL = "0.4.2"
 MetaGraphs = "0.7"
 SparseArrays = "1.9"
-SpinGlassTensors = "1.1.1"
+SpinGlassTensors = "1.1.3"
 julia = "1.9, 1.10"
 
 [extras]

docs/make.jl

@@ -4,10 +4,11 @@ _pages = [
     "User guide" => "userguide.md",
     "Ising graph" => "ising.md",
     "Lattice geometries" => "lattice.md",
-    "Clustered hamiltonian" => "clh.md",
+    "Potts hamiltonian" => "clh.md",
     "Local dimensional reduction" => "bp.md",
-    "API Reference for auxiliary functions" => "api.md",
 ]
+#     "API Reference for auxiliary functions" => "api.md",
+# ]
 
 # ============================
 format =

docs/src/api.md

@@ -11,7 +11,7 @@ prune
 couplings
 ```
 
-## Clustered Hamiltonian
+## Potts Hamiltonian
 ```@docs
 split_into_clusters
 decode_potts_hamiltonian_state

docs/src/bp.md

@@ -1,6 +1,5 @@
 ## Belief propagation
-
-Local dimensional reduction can be achieved by selectively choosing states in the Potts 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.
+The `SpinGlassPEPS.jl` package is capable of handling clusters with up to 24 spins, which results in a total of 2^24 degrees of freedom per cluster. This makes the contraction of the tensor network generated from such a Hamiltonian computationally expensive. To address this, `SpinGlassPEPS.jl` offers an optional feature for local dimensional reduction of cluster degrees of freedom by selectively choosing the most probable states within each cluster. This method reduces the dimensionality of the problem by focusing on the most relevant and energetically favorable states. The marginal probabilities of each Potts variable are approximated using the Loopy Belief Propagation (LBP) algorithm.
 
 ```@docs
 potts_hamiltonian_2site

docs/src/clh.md

@@ -1,7 +1,7 @@
 # Introduction
 A Potts Hamiltonian is a graphical representation that allows for a convenient and intuitive way to describe the structure of a network.
 
-The concept of a Potts Hamiltonian within `SpinGlassNetworks.jl` introduces a mechanism for organizing spins into desired geometries, facilitating a structured approach to modeling complex spin systems. Analogous to a standard factor graph, the Potts Hamiltonian involves nodes that represent tensors within the underlying network. The edges connecting these nodes in the Potts Hamiltonian correspond to the indices shared between the respective tensors in the tensor network.
+The concept of a Potts Hamiltonian within `SpinGlassNetworks.jl` introduces a mechanism for organizing spins into desired clustered geometries, facilitating a structured approach to modeling complex spin systems. 
 
 ```@docs
 potts_hamiltonian
@@ -12,7 +12,7 @@ potts_hamiltonian
 ```@example
 using SpinGlassNetworks
 
-# Prepare simple instance
+# Load instance
 instance = "$(@__DIR__)/../../src/instances/square_diagonal/5x5/diagonal.txt"
 ig = ising_graph(instance)
 

docs/src/lattice.md

@@ -32,7 +32,7 @@ potts_h = potts_hamiltonian(
     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 Potts Hamiltonian: ", length(LabelledGraphs.vertices(potts_h)))
+println("Number of nodes in original instance: ", length(LabelledGraphs.vertices(ig)), "\n", " Number of nodes in Potts Hamiltonian: ", length(LabelledGraphs.vertices(potts_h)))
 ```
 
 ## Pegasus graphs
@@ -52,11 +52,11 @@ Below you find simple example of usage `pegasus_latttice` function.
 ```@example
 using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs
 
-# load Chimera instance and create Ising graph
+# load Pegasus 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
+# Loaded instance is compatible with Pegasus geometry. Next we create Potts hamiltonian based on Pegasus geometry. 
 m = 3
 n = 3
 t = 3
@@ -87,11 +87,11 @@ Below you find simple example of usage `zephyr_latttice` function.
 ```@example
 using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs
 
-# load Chimera instance and create Ising graph
+# load 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
+# Loaded instance is compatible with Zephyr geometry. Next we create Potts hamiltonian based on Zephyr geometry. 
 m = 6
 n = 6
 t = 4
@@ -101,5 +101,5 @@ potts_h = potts_hamiltonian(
     cluster_assignment_rule = zephyr_lattice((m, n, t))
 )
 
-println("Number of nodes in oryginal instance: ", length(LabelledGraphs.vertices(ig)))
+println("Number of nodes in original instance: ", length(LabelledGraphs.vertices(ig)))
 ```

src/ising.jl

@@ -20,7 +20,7 @@ function unique_nodes(ising_tuples)
 end
 
 """
-    ising_graph(instance, sgn::Number = 1.0, rank_override::Dict{Int,Int} = Dict{Int,Int}())
+$(TYPEDSIGNATURES)
 
 Create an Ising graph from interaction data.
 

src/lattice.jl

@@ -43,7 +43,7 @@ The simplified super square lattice is defined by the size of three dimensions:
 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)`, where `m` is number of columns, `n` number of rows and `t` denotes numberr of spins in cluster.
+- `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 number of spins in cluster.
 
 # Returns:
 - `coord_map::Dict`: A dictionary that maps Ising graph coordinates to the corresponding lattice coordinates.
@@ -67,7 +67,7 @@ This function generates a mapping that relates Ising graph coordinates to Pegasu
 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)`, where `m` is number of columns, `n` number of rows and `t` denotes number of spins in cluster. Convention: `t` is already divided by 8, so `t`=3 for Pegasus lattice.
+- `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 number of spins in the cluster. One Pegasus cluster consists of 24 spins. Convention: `t` is already divided by 8, so `t`=3 for Pegasus lattice.
 
 # Returns:
 - `coord_map::Dict`: A dictionary that maps Ising graph coordinates to the corresponding Pegasus lattice coordinates.
@@ -160,7 +160,7 @@ This function generates a mapping that relates Ising graph coordinates to Zephyr
 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)`, 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. E.g. to create 3x3x16 Zephyr lattice, you should use `m`=6, `n`=6, `t`=4.
+- `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. One full Zephyr cluster consists of 16 spins. Convention: `t` is already divided by 4, so `t`=4 for Zephyr lattice. E.g. to create 3x3x16 Zephyr lattice, you should use `m`=6, `n`=6, `t`=4.
 
 # Returns:
 - `coord_map::Dict`: A dictionary that maps Ising graph coordinates to the corresponding Zephyr lattice coordinates.

test/bp_2site.jl

@@ -170,10 +170,10 @@ end
                 E = get_prop(new_potts_h1, src(e), dst(e), :en)
                 # @cast E[(l1, l2), (r1, r2)] :=
                 #     E.e11[l1, r1] + E.e21[l2, r1] + E.e12[l1, r2] + E.e22[l2, r2]
-                a11 = reshape(CuArray(E.e11), size(E.e11, 1), :, size(E.e11, 2))
-                a21 = reshape(CuArray(E.e21), :, size(E.e21, 1), size(E.e21, 2))
-                a12 = reshape(CuArray(E.e12), size(E.e12, 1), 1, 1, size(E.e12, 2))
-                a22 = reshape(CuArray(E.e22), 1, size(E.e22, 1), 1, size(E.e22, 2))
+                a11 = reshape(onGPU ? CuArray(E.e11) : E.e11, size(E.e11, 1), :, size(E.e11, 2))
+                a21 = reshape(onGPU ? CuArray(E.e21) : E.e21, :, size(E.e21, 1), size(E.e21, 2))
+                a12 = reshape(onGPU ? CuArray(E.e12) : E.e12, size(E.e12, 1), 1, 1, size(E.e12, 2))
+                a22 = reshape(onGPU ? CuArray(E.e22) : E.e22, 1, size(E.e22, 1), 1, size(E.e22, 2))
                 E = @__dot__(a11 + a21 + a12 + a22)
                 E = reshape(E, size(E, 1) * size(E, 2), size(E, 3) * size(E, 4))
                 @test Array(E) == get_prop(potts_h1, src(e), dst(e), :en)

test/runtests.jl

@@ -7,6 +7,9 @@ using Logging
 using Test
 using CUDA
 
+user_onGPU = true  # or false, based on user's preference
+gpu_available = CUDA.functional()
+onGPU = user_onGPU && gpu_available
 
 function _energy(config::Dict, couplings::Dict, cedges::Dict, n::Int)
     eng = zeros(1, n)