Merge branch 'master' into lp/julia-1.11

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.4.0"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"

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,17 +11,17 @@ prune
 couplings
 ```
 
-## Clustered Hamiltonian
+## Potts Hamiltonian
 ```@docs
 split_into_clusters
-decode_clustered_hamiltonian_state
+decode_potts_hamiltonian_state
 rank_reveal
 energy
 energy_2site
 cluster_size
 bond_energy
 exact_cond_prob
-truncate_clustered_hamiltonian
+truncate_potts_hamiltonian
 ```
 
 ## Belief propagation
@@ -31,7 +31,7 @@ interaction_energy
 get_neighbors
 MergedEnergy
 update_message
-merge_vertices_cl_h
+merge_vertices_potts_h
 projector
 SparseCSC
 ```
@@ -54,8 +54,8 @@ brute_force
 
 ## Truncate
 ```@docs
-truncate_clustered_hamiltonian_1site_BP
-truncate_clustered_hamiltonian_2site_energy
+truncate_potts_hamiltonian_1site_BP
+truncate_potts_hamiltonian_2site_energy
 select_numstate_best
 ```
 

docs/src/bp.md

@@ -1,9 +1,8 @@
 ## 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.
+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
-clustered_hamiltonian_2site
+potts_hamiltonian_2site
 belief_propagation
-truncate_clustered_hamiltonian_2site_BP
+truncate_potts_hamiltonian_2site_BP
 ```

docs/src/clh.md

@@ -1,23 +1,23 @@
 # Introduction
-A clustered Hamiltonian is a graphical representation that allows for a convenient and intuitive way to describe the structure of a network.
+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 clustered 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 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 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
-clustered_hamiltonian
+potts_hamiltonian
 ```
 
 ## Simple example
 
 ```@example
 using SpinGlassNetworks
 
-# Prepare simple instance
+# Load instance
 instance = "$(@__DIR__)/../../src/instances/square_diagonal/5x5/diagonal.txt"
 ig = ising_graph(instance)
 
-# Create clustered Hamiltonian
-cl_h = clustered_hamiltonian(
+# Create Potts Hamiltonian
+potts_h = potts_hamiltonian(
     ig,
     cluster_assignment_rule = super_square_lattice((5,5,4))
 )

docs/src/lattice.md

@@ -1,5 +1,5 @@
 # Lattice geometries
-The Ising graph allowed for loading instances directly from a file and translating them 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.
+The Ising graph allowed for loading instances directly from a file and translating them 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 Potts Hamiltonian.
 Within the `SpinGlassNetworks.jl` package, users have the flexibility to construct three types of lattice geometries, each tailored to specific needs. 
 
 ## Super square lattice
@@ -27,12 +27,12 @@ m = 5
 n = 5
 t = 4
 
-cl_h = clustered_hamiltonian(
+potts_h = potts_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)))
+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,21 +52,21 @@ 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
 
-cl_h = clustered_hamiltonian(
+potts_h = potts_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))/2)
+println("Number of nodes in original instance: ", length(LabelledGraphs.vertices(ig)), "\n", " Number of nodes in Potts Hamiltonian: ", length(LabelledGraphs.vertices(potts_h))/2)
 ```
 
 
@@ -87,19 +87,19 @@ 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
 
-cl_h = clustered_hamiltonian(
+potts_h = potts_hamiltonian(
     ig,
     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)))
 ```

docs/src/userguide.md

@@ -2,4 +2,4 @@
 
 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.
 
-The contents of our package are 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 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.
+The contents of our package are 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 `potts_hamiltonian` function is presented as a tool for converting Ising graphs into Potts 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.

examples/bp.jl

@@ -13,7 +13,7 @@ Instance below looks like this:
 |
 7 -- 8 -- 9
 """
-function create_larger_example_clustered_hamiltonian_tree()
+function create_larger_example_potts_hamiltonian_tree()
     instance = Dict(
         (1, 1) => 0.5,
         (2, 2) => 0.25,
@@ -48,22 +48,22 @@ function create_larger_example_clustered_hamiltonian_tree()
         9 => (3, 3, 1),
     )
 
-    cl_h = clustered_hamiltonian(
+    potts_h = potts_hamiltonian(
         ig,
         Dict{NTuple{3,Int},Int}(),
         spectrum = full_spectrum,
         cluster_assignment_rule = assignment_rule,
     )
 
-    ig, cl_h
+    ig, potts_h
 end
 
-ig, cl_h = create_larger_example_clustered_hamiltonian_tree()
+ig, potts_h = create_larger_example_potts_hamiltonian_tree()
 beta = 0.1
 iter = 0
-beliefs = belief_propagation(cl_h, beta; iter = iter)
+beliefs = belief_propagation(potts_h, beta; iter = iter)
 
-for v in vertices(cl_h)
-    en = get_prop(cl_h, v, :spectrum).energies
+for v in vertices(potts_h)
+    en = get_prop(potts_h, v, :spectrum).energies
     println("vertex ", v, " energy = ", en .- minimum(en), " bp = ", beliefs[v])
 end

examples/temp.jl

@@ -81,34 +81,34 @@ function load_openGM(fname::String, Nx::Integer, Ny::Integer)
     result
 end
 
-function clustered_hamiltonian(fname::String, Nx::Integer = 240, Ny::Integer = 320)
+function potts_hamiltonian(fname::String, Nx::Integer = 240, Ny::Integer = 320)
     loaded_rmf = load_openGM(fname, Nx, Ny)
     functions = loaded_rmf["fun"]
     factors = loaded_rmf["fac"]
     N = loaded_rmf["N"]
 
     clusters = super_square_lattice((Nx, Ny, 1))
-    cl_h = LabelledGraph{MetaDiGraph}(sort(collect(values(clusters))))
-    for v ∈ cl_h.labels
+    potts_h = LabelledGraph{MetaDiGraph}(sort(collect(values(clusters))))
+    for v ∈ potts_h.labels
         x, y = v
         sp = Spectrum(
             Vector{Real}(undef, 1),
             Array{Vector{Int}}(undef, 1, 1),
             Vector{Int}(undef, 1),
         )
-        set_props!(cl_h, v, Dict(:cluster => v, :spectrum => sp))
+        set_props!(potts_h, v, Dict(:cluster => v, :spectrum => sp))
     end
     for (index, value) in factors
         if length(index) == 2
             y, x = index
             Eng = sum(functions[value])
-            set_props!(cl_h, (x + 1, y + 1), Dict(:eng => Eng))
+            set_props!(potts_h, (x + 1, y + 1), Dict(:eng => Eng))
         elseif length(index) == 4
             y1, x1, y2, x2 = index
-            add_edge!(cl_h, (x1 + 1, y1 + 1), (x2 + 1, y2 + 1))
+            add_edge!(potts_h, (x1 + 1, y1 + 1), (x2 + 1, y2 + 1))
             Eng = sum(functions[value], dims = 2)
             set_props!(
-                cl_h,
+                potts_h,
                 (x1 + 1, y1 + 1),
                 (x2 + 1, y2 + 1),
                 Dict(
@@ -127,12 +127,12 @@ function clustered_hamiltonian(fname::String, Nx::Integer = 240, Ny::Integer = 3
         end
     end
 
-    cl_h
+    potts_h
 end
 
 
 x, y = 240, 320
 filename = "/home/tsmierzchalski/.julia/dev/SpinGlassNetworks/examples/penguin-small.h5"
 
 
-cf = clustered_hamiltonian(filename, x, y)
+cf = potts_hamiltonian(filename, x, y)

src/SpinGlassNetworks.jl

@@ -15,7 +15,7 @@ import Base.Prehashed
 include("ising.jl")
 include("spectrum.jl")
 include("lattice.jl")
-include("clustered_hamiltonian.jl")
+include("potts_hamiltonian.jl")
 include("bp.jl")
 include("truncate.jl")
 include("utils.jl")