From d7311b4f7ac56200ad3064d576903d68a9ae1c65 Mon Sep 17 00:00:00 2001 From: annamariadziubyna <73058800+annamariadziubyna@users.noreply.github.com> Date: Mon, 27 Nov 2023 13:07:04 +0100 Subject: [PATCH] add the docs --- docs/src/clh.md | 2 +- docs/src/ising.md | 2 +- docs/src/lattice.md | 8 +++---- docs/src/userguide.md | 2 +- src/bp.jl | 25 ++++++++++----------- src/clustered_hamiltonian.jl | 33 ++++++++++++--------------- src/ising.jl | 5 +++-- src/lattice.jl | 43 ++++++++++++++++++------------------ src/truncate.jl | 2 +- 9 files changed, 58 insertions(+), 64 deletions(-) diff --git a/docs/src/clh.md b/docs/src/clh.md index 6f11909..c3ba34a 100644 --- a/docs/src/clh.md +++ b/docs/src/clh.md @@ -1,7 +1,7 @@ # Introduction A clustered 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 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 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. ```@docs clustered_hamiltonian diff --git a/docs/src/ising.md b/docs/src/ising.md index 2d24bb9..f2bec58 100644 --- a/docs/src/ising.md +++ b/docs/src/ising.md @@ -12,7 +12,7 @@ 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. +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 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 diff --git a/docs/src/lattice.md b/docs/src/lattice.md index a2a44d4..773462e 100644 --- a/docs/src/lattice.md +++ b/docs/src/lattice.md @@ -1,10 +1,10 @@ -## 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. +# 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. +Within the `SpinGlassNetworks.jl` package, users have the flexibility to construct three types of lattice geometries, each tailored to specific needs. ## Super square lattice 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. +This geometry allows for an exploration of spin interactions beyond the traditional square lattice framework. ```@raw html ``` diff --git a/docs/src/userguide.md b/docs/src/userguide.md index c3d7b52..cb92310 100644 --- a/docs/src/userguide.md +++ b/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 richly 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 pivotal 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 `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. diff --git a/src/bp.jl b/src/bp.jl index bc8286f..92ab0f4 100644 --- a/src/bp.jl +++ b/src/bp.jl @@ -13,23 +13,22 @@ export """ $(TYPEDSIGNATURES) -Perform belief propagation on a given clustered hamiltonian. +Perform loopy belief propagation on a given clustered Hamiltonian. # Arguments: -- `cl_h::LabelledGraph{S, T}`: The clustered hamiltonian represented as a labeled graph. -- `beta::Real`: The temperature parameter for the belief propagation algorithm. -- `tol::Real (optional, default=1e-6)`: The convergence tolerance. -The algorithm stops when the message updates between iterations are smaller than this value. +- `cl_h::LabelledGraph{S, T}`: The clustered Hamiltonian represented as a labelled graph. +- `beta::Real`: The inverse temperature parameter for the belief propagation algorithm. +- `tol::Real (optional, default=1e-6)`: The convergence tolerance. The algorithm stops when the message updates between iterations are smaller than this value. - `iter::Int (optional, default=1)`: The maximum number of iterations to perform. # Returns: - `beliefs::Dict`: A dictionary where keys are vertices of clustered hamiltonian, and values are the resulting beliefs after belief propagation. -The function implements belief propagation on the given clustered hamiltonian `cl_h` to calculate beliefs for each vertex. +The function implements loopy belief propagation on the given clustered hamiltonian `cl_h` to calculate beliefs for each vertex. Belief propagation is an iterative algorithm that computes beliefs by passing messages between vertices and edges of the clustered hamiltonian. The algorithm continues until convergence or until the specified maximum number of iterations is reached. -The beliefs are computed based on the temperature parameter `beta`, which controls the influence of energy values on the beliefs. +The beliefs are computed based on the inverse temperature parameter `beta`, which controls the influence of energy values on the beliefs. """ function belief_propagation(cl_h::LabelledGraph{S, T}, beta::Real; tol=1e-6, iter=1) where {S, T} messages_ve = Dict() @@ -247,17 +246,17 @@ end """ $(TYPEDSIGNATURES) -Constructs a clustered Hamiltonian for a given clustered Hamiltonian with a 2-site cluster approximation. +Constructs a clustered Hamiltonian for a given clustered Hamiltonian with a 2-site cluster approximation used in Pegasus graph. # Arguments: -- `cl_h::LabelledGraph{S, T}`: The clustered Hamiltonian represented as a labeled graph. -- `beta::Real`: The temperature parameter for the 2-site cluster Hamiltonian construction. +- `cl_h::LabelledGraph{S, T}`: The clustered Hamiltonian represented as a labelled graph. +- `beta::Real`: The inverse temperature parameter for the 2-site cluster Hamiltonian construction. # Returns: -- `new_cl_h::LabelledGraph{MetaDiGraph}`: A new labeled graph representing the 2-site cluster Hamiltonian. +- `new_cl_h::LabelledGraph{MetaDiGraph}`: A new labelled graph representing the 2-site cluster Hamiltonian. - This function constructs a clustered Hamiltonian `cl_h` by applying a 2-site cluster approximation. - It combines and merges vertices and edges of the original graph to create a simplified representation of the Hamiltonian. +This function constructs a clustered Hamiltonian `cl_h` by applying a 2-site cluster approximation. +It combines and merges vertices and edges of the original graph to create a simplified representation of the Hamiltonian. The resulting `new_cl_h` graph represents the 2-site cluster Hamiltonian with simplified interactions between clusters. The energy values, projectors, and spectra associated with the new vertices and edges are computed based on diff --git a/src/clustered_hamiltonian.jl b/src/clustered_hamiltonian.jl index eeead8c..d1a3a89 100644 --- a/src/clustered_hamiltonian.jl +++ b/src/clustered_hamiltonian.jl @@ -46,19 +46,17 @@ This function constructs a clustered Hamiltonian from an Ising graph by introduc # Arguments: - `ig::IsingGraph`: The Ising graph representing the spin system. -- `num_states_cl::Int`: The number of states per cluster. -- `spectrum::Function`: A function for calculating the spectrum of the clustered Hamiltonian. -- `cluster_assignment_rule::Dict{Int, L}`: A dictionary specifying the assignment rule that maps Ising graph vertices to clusters. +- `num_states_cl::Int`: The number of states per cluster taken into account when calculating the spectrum. In every cluster the number of states is constant. +- `spectrum::Function`: A function for calculating the spectrum of the clustered Hamiltonian. It can be `full_spectrum` or `brute_force`. +- `cluster_assignment_rule::Dict{Int, L}`: A dictionary specifying the assignment rule that maps Ising graph vertices to clusters. It can be `super_square_lattice`, `pegasus_lattice` or `zephyr_lattice`. # Returns: -- `cl_h::LabelledGraph{S, T}`: The clustered Hamiltonian represented as a labeled graph. +- `cl_h::LabelledGraph{S, T}`: The clustered Hamiltonian represented as a labelled graph. The `clustered_hamiltonian` function takes an Ising graph (`ig`) as input and constructs a clustered Hamiltonian by introducing a natural order in clustered Hamiltonian coordinates. It allows you to specify the number of states per cluster, a spectrum calculation function, and a cluster assignment rule, which maps Ising graph vertices to clusters. - -This function is useful for organizing and studying spin systems in a clustered Hamiltonian framework. """ function clustered_hamiltonian( ig::IsingGraph, @@ -79,18 +77,17 @@ This function constructs a clustered Hamiltonian from an Ising graph by introduc # Arguments: - `ig::IsingGraph`: The Ising graph representing the spin system. -- `num_states_cl::Dict{T, Int}`: A dictionary specifying the number of states per cluster for different clusters. -- `spectrum::Function`: A function for calculating the spectrum of the clustered Hamiltonian. -- `cluster_assignment_rule::Dict{Int, T}`: A dictionary specifying the assignment rule that maps Ising graph vertices to clusters. +- `num_states_cl::Dict{T, Int}`: A dictionary specifying the number of states per cluster for different clusters. Number of states are considered when calculating the spectrum. +- `spectrum::Function`: A function for calculating the spectrum of the clustered Hamiltonian. It can be `full_spectrum` or `brute_force`. +- `cluster_assignment_rule::Dict{Int, T}`: A dictionary specifying the assignment rule that maps Ising graph vertices to clusters. It can be `super_square_lattice`, `pegasus_lattice` or `zephyr_lattice`. # Returns: -- `cl_h::LabelledGraph{MetaDiGraph}`: The clustered Hamiltonian represented as a labeled graph. +- `cl_h::LabelledGraph{MetaDiGraph}`: The clustered Hamiltonian represented as a labelled graph. The `clustered_hamiltonian` function takes an Ising graph (`ig`) as input and constructs a clustered Hamiltonian by introducing a natural order in clustered Hamiltonian coordinates. It allows you to specify the number of -states per cluster, a spectrum calculation function, and a cluster assignment rule, which maps Ising graph vertices to clusters. - -This function is useful for organizing and studying spin systems in a clustered Hamiltonian framework. +states per cluster which can vary for different clusters, a spectrum calculation function, +and a cluster assignment rule, which maps Ising graph vertices to clusters. """ function clustered_hamiltonian( @@ -149,20 +146,18 @@ This function constructs a clustered Hamiltonian from an Ising graph by introduc # Arguments: - `ig::IsingGraph`: The Ising graph representing the spin system. -- `spectrum::Function`: A function for calculating the spectrum of the clustered Hamiltonian. -- `cluster_assignment_rule::Dict{Int, T}`: A dictionary specifying the assignment rule that maps Ising graph vertices to clusters. +- `spectrum::Function`: A function for calculating the spectrum of the clustered Hamiltonian. It can be `full_spectrum` or `brute_force`. Default is `full_spectrum`. +- `cluster_assignment_rule::Dict{Int, T}`: A dictionary specifying the assignment rule that maps Ising graph vertices to clusters. It can be `super_square_lattice`, `pegasus_lattice` or `zephyr_lattice`. # Returns: -- `cl_h::LabelledGraph{MetaDiGraph}`: The clustered Hamiltonian represented as a labeled graph. +- `cl_h::LabelledGraph{MetaDiGraph}`: The clustered Hamiltonian represented as a labelled graph. The `clustered_hamiltonian` function takes an Ising graph (`ig`) as input and constructs a clustered Hamiltonian by introducing a natural order in clustered Hamiltonian coordinates. You can optionally specify a spectrum calculation function and a cluster assignment rule, which maps Ising graph vertices to clusters. - +This version of `clustered_hamiltonian` function does not truncate states in the cluster while calculating the spectrum. If you want to specify custom cluster sizes, use the alternative version of this function by passing a `Dict{T, Int}` containing the number of states per cluster as `num_states_cl`. - -This function is useful for organizing and studying spin systems in a clustered Hamiltonian framework. """ function clustered_hamiltonian( ig::IsingGraph; diff --git a/src/ising.jl b/src/ising.jl index 04e2207..4229ec3 100644 --- a/src/ising.jl +++ b/src/ising.jl @@ -26,7 +26,8 @@ $(TYPEDSIGNATURES) Create an Ising graph from interaction data. This function creates an Ising graph (LabelledGraph) from interaction data provided in the form of an `inst` argument. -The Ising graph represents a system of spins, where each spin is associated with a vertex, and interactions between spins are represented as edges with corresponding weights. +The Ising graph represents a system of spins, where each spin is associated with a vertex, +and interactions between spins are represented as edges with corresponding weights. # Arguments: - `::Type{T}`: The type of the edge weights, typically `Float64` or `Float32`. @@ -38,7 +39,7 @@ The Ising graph represents a system of spins, where each spin is associated with - `ig::IsingGraph{T}`: The Ising graph (LabelledGraph) representing the spin system. The function reads interaction data and constructs an Ising graph `ig`. -It assigns interaction strengths to edges between spins and optionally scales them by the `scale` factor. +It assigns interaction strengths to edges between spins and optionally scales them by the `scale` factor. 'Scale' option allows for the change of convention in the Hamiltonian. The `rank_override` dictionary can be used to specify the rank (number of states) for individual vertices, allowing customization of the Ising model. Convention: H = scale * sum_{i, j} (J_{ij} * s_i * s_j + J_{ii} * s_i) """ diff --git a/src/lattice.jl b/src/lattice.jl index 971e5c6..5ef94c4 100644 --- a/src/lattice.jl +++ b/src/lattice.jl @@ -12,21 +12,21 @@ export """ $(TYPEDSIGNATURES) -Create a mapping from clustered Hamiltonian coordinates to a super square lattice arrangement. -Variable number of Ising graph -> Factor graph coordinate system +Create a mapping from Ising graph coordinates to a super square lattice arrangement. +Variable number of Ising graph -> cluster hamiltonian coordinate system -This function generates a mapping that relates clustered Hamiltonian coordinates to a super square lattice arrangement. +This function generates a mapping that relates Ising graph coordinates to a super square lattice arrangement. The super square lattice is defined by the size of five dimensions: `(m, um, n, un, t)`, -where m is the number of columns, m is the number of rows and t denotes the number of spins stored in the cluster. +where m is the number of columns, n is the number of rows and t denotes the number of spins stored in the cluster. # Arguments: - `size::NTuple{5, Int}`: A tuple specifying the size of the super square lattice in five dimensions: `(m, um, n, un, t)`. # Returns: -- `coord_map::Dict`: A dictionary that maps clustered Hamiltonian coordinates to the corresponding lattice coordinates. +- `coord_map::Dict`: A dictionary that maps Ising graph coordinates to the corresponding lattice coordinates. The `size` tuple represents the dimensions of the super square lattice. The function creates a dictionary where -clustered Hamiltonian coordinates are associated with their corresponding lattice coordinates. +ising graph coordinates are associated with their corresponding lattice coordinates. """ function super_square_lattice(size::NTuple{5, Int}) m, um, n, un, t = size @@ -37,16 +37,17 @@ end """ $(TYPEDSIGNATURES) -Create a mapping from clustered Hamiltonian coordinates to a simplified super square lattice arrangement. +Create a mapping from Ising graph coordinates to a simplified super square lattice arrangement. -This function generates a mapping that relates clustered Hamiltonian coordinates to a simplified super square lattice arrangement. -The simplified super square lattice is defined by the size of three dimensions: `(m, n, t)`, where m is the number of columns, n is the number of rows and t denotes the number of spins stored in the cluster. +This function generates a mapping that relates Ising graph coordinates to a simplified super square lattice arrangement. +The simplified super square lattice is defined by the size of three dimensions: `(m, n, t)`, where m is the number of columns, +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. # Returns: -- `coord_map::Dict`: A dictionary that maps clustered Hamiltonian coordinates to the corresponding lattice coordinates. +- `coord_map::Dict`: A dictionary that maps Ising graph coordinates to the corresponding lattice coordinates. The `size` tuple represents the dimensions of the simplified super square lattice. The function internally adds the required dimensions `(1, 1)` to make it compatible with the `super_square_lattice` function, which deals with five dimensions. @@ -61,19 +62,18 @@ pegasus_lattice(size::NTuple{2, Int}) = pegasus_lattice((size[1], size[2], 3)) """ $(TYPEDSIGNATURES) -Create a mapping from clustered Hamiltonian coordinates to Pegasus lattice coordinates. +Create a mapping from Ising graph coordinates to Pegasus lattice coordinates. -This function generates a mapping that relates clustered Hamiltonian coordinates to Pegasus lattice coordinates +This function generates a mapping that relates Ising graph coordinates to Pegasus lattice coordinates 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 numberr 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 cluster. Convention: `t` is already divided by 8, so `t`=3 for Pegasus lattice. # Returns: -- `coord_map::Dict`: A dictionary that maps clustered Hamiltonian coordinates to the corresponding Pegasus lattice coordinates. +- `coord_map::Dict`: A dictionary that maps Ising graph coordinates to the corresponding Pegasus lattice coordinates. -The Pegasus lattice is a specialized lattice used in quantum computing, and this function allows you to convert -between clustered Hamiltonian coordinates and Pegasus lattice coordinates. +The `pegasus_lattice` allows you to build the graph relevant for D-Wave Pegasus architecture. """ function pegasus_lattice(size::NTuple{3, Int}) m, n, t = size @@ -137,19 +137,18 @@ zephyr_lattice(size::NTuple{2, Int}) = zephyr_lattice((size[1], size[2], 4)) """ $(TYPEDSIGNATURES) -Create a mapping from clustered Hamiltonian coordinates to Zephyr lattice coordinates. +Create a mapping from Ising graph coordinates to Zephyr lattice coordinates. -This function generates a mapping that relates clustered Hamiltonian coordinates to Zephyr lattice +This function generates a mapping that relates Ising graph coordinates to Zephyr lattice 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. +- `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. # Returns: -- `coord_map::Dict`: A dictionary that maps clustered Hamiltonian coordinates to the corresponding Zephyr lattice coordinates. +- `coord_map::Dict`: A dictionary that maps Ising graph coordinates to the corresponding Zephyr lattice coordinates. -The Zephyr lattice is a specialized lattice used in quantum computing, and this function allows you to -convert between clustered Hamiltonian coordinates and Zephyr lattice coordinates. +The `zephyr_lattice` allows you to build the graph relevant for D-Wave Zephyr architecture. """ function zephyr_lattice(size::NTuple{3, Int}) m, n, t = size diff --git a/src/truncate.jl b/src/truncate.jl index 1ae5f63..b434200 100644 --- a/src/truncate.jl +++ b/src/truncate.jl @@ -80,7 +80,7 @@ This function truncates a clustered Hamiltonian by considering 2-site belief pro to keep. It computes the beliefs for all 2-site combinations and selects the states that maximize the probability. # Arguments: -- `cl_h::LabelledGraph{S, T}`: The clustered Hamiltonian represented as a labeled graph. +- `cl_h::LabelledGraph{S, T}`: The clustered Hamiltonian represented as a labelled graph. - `beliefs::Dict`: A dictionary containing belief values for 2-site interactions. - `num_states::Int`: The maximum number of most probable states to keep. - `beta::Real (optional)`: The inverse temperature parameter (default is 1.0).