diff --git a/docs/src/api.md b/docs/src/api.md index 6e09308..41c9be0 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -14,14 +14,12 @@ couplings ## Potts Hamiltonian ```@docs split_into_clusters -decode_potts_hamiltonian_state rank_reveal energy energy_2site cluster_size bond_energy exact_cond_prob -truncate_potts_hamiltonian ``` ## Belief propagation diff --git a/docs/src/bp.md b/docs/src/bp.md index ac5baf6..4f0f7b0 100644 --- a/docs/src/bp.md +++ b/docs/src/bp.md @@ -1,7 +1,10 @@ -## 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. +## Local dimensional reduction of cluster degrees of freedom +The `SpinGlassPEPS.jl` package addresses the computational challenges posed by large unit cells, which result in a high number of degrees of freedom per cluster. Contracting tensor networks generated from such Hamiltonians can become numerically expensive. To mitigate this, the package provides an optional local dimensional reduction feature, which reduces the problem's complexity by focusing on the most probable states within each cluster. + +This dimensionality reduction is achieved by approximating the marginal probabilities of Potts variables using the Loopy Belief Propagation (LBP) algorithm. LBP iteratively updates messages between clusters and edges to approximate the likelihood of configurations within each cluster. While exact convergence is guaranteed only for tree-like graphs, this method effectively selects a subset of energetically favorable states, even for geometries with loops, such as Pegasus and Zephyr lattices. The details of the Loopy Belief Propagation algorithm are described in [Ref.](https://arxiv.org/abs/2411.16431) ```@docs +truncate_potts_hamiltonian potts_hamiltonian_2site belief_propagation truncate_potts_hamiltonian_2site_BP diff --git a/docs/src/clh.md b/docs/src/clh.md index f5fef43..4476895 100644 --- a/docs/src/clh.md +++ b/docs/src/clh.md @@ -1,7 +1,5 @@ # 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 clustered geometries, facilitating a structured approach to modeling complex spin systems. +In `SpinGlassNetworks.jl`, the Potts Hamiltonian serves as a framework for transforming Ising graphs into clustered representations, enabling efficient modeling of complex spin systems. Instead of treating individual spins as separate variables, spins are grouped into clusters corresponding to unit cells of a given lattice geometry. This process reduces the number of variables while increasing their dimensionality, making the system more manageable for tensor-network-based approaches. ```@docs potts_hamiltonian diff --git a/docs/src/lattice.md b/docs/src/lattice.md index 9fea3a7..285d0dc 100644 --- a/docs/src/lattice.md +++ b/docs/src/lattice.md @@ -1,10 +1,11 @@ # 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 Potts Hamiltonian. -Within the `SpinGlassNetworks.jl` package, users have the flexibility to construct three types of lattice geometries, each tailored to specific needs. +The Ising graph serves as the starting point, allowing users to load instances directly from a file and translate them into a graph with vertices numerated using linear indices. To group spins into clusters for the Potts Hamiltonian, it is necessary to map these linear spin coordinates onto the corresponding coordinates of a Potts clusters in a specific lattice geometry. + +The `SpinGlassNetworks.jl` package provides tools for mapping linear indices into three types of lattice geometries, enabling users to adapt the mapping process to the structure of the problem being analyzed. These geometries include super square lattice, Pegasus lattice, and Zephyr lattice, each optimized for specific topologies and applications. For example, in the Pegasus lattice, groups of 24 binary spins are clustered into a single Potts variable, while in the Zephyr lattice, clusters consist of 16 binary spins. ## 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 an exploration of spin interactions beyond the traditional square lattice framework. +The `super_square_lattice` geometry defines a square lattice with interactions between nearest neighbors (horizontal and vertical connections between unit cells) and next-nearest neighbors (diagonal connections). In `super_square_lattice` function, linear indices of spins from the Ising graph are mapped onto a 2D super square lattice coordinate system (King's lattice). +Spins (denoted as black dots in the figure below) are grouped into clusters represented as red ellipses. Every spin in this cluster is indexed coresponding to the square lattice coordinate in the new graph with reduced number of variables of higher dimensions (shown on the right). ```@raw html ``` diff --git a/docs/src/userguide.md b/docs/src/userguide.md index e9d8313..d437198 100644 --- a/docs/src/userguide.md +++ b/docs/src/userguide.md @@ -1,5 +1,5 @@ # Introduction -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. +A [Julia](http://julialang.org) package for generating an Ising graphs and clustering binary variables to create effective Potts Hamiltonians. 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 `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. +The contents of `SpinGlassNetworks.jl` package is illustrated through comprehensive examples, showcasing the practical utilization of key functions. Specifically, the `ising_graph` function is highlighted, demonstrating its capacity to generate Ising graphs from a given instance using a set of standard inputs (e.g., instances compatible with the Ocean environment provided by D-Wave). Additionally, the `potts_hamiltonian` function is presented as a tool for grouping binary variables into clusters with a reduced number of variables of larger dimensions, creating effective Potts Hamiltonians. The package delves into various lattice geometries, providing reindexing of linear Ising coordinates into `super_square_lattice`, `pegasus_lattice`, and `zephyr_lattice`. Moreover, the documentation outlines methods for local dimensional reduction of cluster degrees of freedom. diff --git a/src/bp.jl b/src/bp.jl index 0b62afb..6d9bbc6 100644 --- a/src/bp.jl +++ b/src/bp.jl @@ -21,8 +21,7 @@ Perform loopy belief propagation on a given Potts Hamiltonian. - `iter::Int (optional, default=1)`: The maximum number of iterations to perform. # Returns: -- `beliefs::Dict`: A dictionary where keys are vertices of Potts Hamiltonian, and values are the -resulting beliefs after belief propagation. +- `beliefs::Dict`: A dictionary mapping the vertices of the Potts Hamiltonian to the computed belief distributions of states within each cluster. The function implements loopy belief propagation on the given Potts Hamiltonian `potts_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 Potts Hamiltonian. @@ -255,21 +254,20 @@ end """ $(TYPEDSIGNATURES) -Constructs a Potts Hamiltonian for a given Potts Hamiltonian with a 2-site cluster approximation used in Pegasus graph. +Construct a 2-site cluster approximation of a Potts Hamiltonian. + +This function generates a new Potts Hamiltonian using a 2-site cluster approximation, specifically designed for geometries like Pegasus and Zephyr. +In these geometries, clusters in the original Potts Hamiltonian are subdivided into smaller sub-clusters, which are then merged into unified 2-site clusters. # Arguments: -- `potts_h::LabelledGraph{S, T}`: The Potts Hamiltonian represented as a labelled graph. -- `beta::Real`: The inverse temperature parameter for the 2-site cluster Hamiltonian construction. - +- `potts_h::LabelledGraph{S, T}`: The input Potts Hamiltonian represented as a labelled graph, where vertices correspond to individual sub-clusters and edges define interactions between them. +- `beta::Real`: The inverse temperature parameter, used for computing the energy values and spectra of the 2-site clusters. + # Returns: -- `new_potts_h::LabelledGraph{MetaDiGraph}`: A new labelled graph representing the 2-site cluster Hamiltonian. - -This function constructs a Potts Hamiltonian `potts_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_potts_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 -the provided temperature parameter `beta`. +- `new_potts_h::LabelledGraph{MetaDiGraph}`: A labelled graph representing the new Potts Hamiltonian, where: + - Vertices: Represent unified 2-site clusters. + - Edges: Capture interactions between these clusters, including energy values and associated projectors. + """ function potts_hamiltonian_2site(potts_h::LabelledGraph{S,T}, beta::Real) where {S,T} diff --git a/src/lattice.jl b/src/lattice.jl index 2fa5b6d..ad097f0 100644 --- a/src/lattice.jl +++ b/src/lattice.jl @@ -8,25 +8,6 @@ export super_square_lattice, zephyr_lattice_5tuple_rotated, periodic_lattice -""" -$(TYPEDSIGNATURES) - -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 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, 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 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 -ising graph coordinates are associated with their corresponding lattice coordinates. -""" function super_square_lattice(size::NTuple{5,Int}) m, um, n, un, t = size old = LinearIndices((1:t, 1:un, 1:n, 1:um, 1:m)) @@ -36,20 +17,17 @@ end """ $(TYPEDSIGNATURES) -Create a mapping from Ising graph coordinates to a simplified super square lattice arrangement. +Create a mapping from Ising graph coordinates to a super square lattice arrangement. -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. +This function generates a mapping that relates linear Ising graph coordinates to a super square lattice arrangement. +The 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 number of spins in cluster. +- `size::NTuple{3, Int}`: A tuple specifying the size of the 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. - -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. """ function super_square_lattice(size::NTuple{3,Int}) m, n, t = size @@ -67,10 +45,12 @@ 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 the cluster. One Pegasus cluster consists of 24 spins. 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. +- `coord_map::Dict`: A dictionary that maps linear Ising graph coordinates to the corresponding Pegasus lattice coordinates. The `pegasus_lattice` allows you to build the graph relevant for D-Wave Pegasus architecture. """ @@ -156,11 +136,14 @@ $(TYPEDSIGNATURES) Create a mapping from Ising graph coordinates to Zephyr lattice coordinates. -This function generates a mapping that relates Ising graph coordinates to Zephyr lattice +This function generates a mapping that relates linear 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. 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. +- `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. diff --git a/src/potts_hamiltonian.jl b/src/potts_hamiltonian.jl index a70a9d9..7293137 100644 --- a/src/potts_hamiltonian.jl +++ b/src/potts_hamiltonian.jl @@ -41,23 +41,25 @@ end """ $(TYPEDSIGNATURES) -Create a Potts Hamiltonian. +Construct a Potts Hamiltonian. -This function constructs a Potts Hamiltonian from an Ising graph by introducing a natural order in Potts Hamiltonian coordinates. +This function converts an Ising graph into a Potts Hamiltonian by clustering spins into groups defined by a given lattice geometry. Each cluster is assigned a fixed number of states. # Arguments: -- `ig::IsingGraph`: The Ising graph representing the spin system. -- `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 Potts 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`. +- `ig::IsingGraph`: The input Ising graph, representing the spin system as a set of vertices (spins) and edges (interactions). +- `num_states_cl::Int`: The number of states assigned to each cluster. All clusters are assigned the same number of states. +- `spectrum::Function`: A function for computing the spectrum of the Potts Hamiltonian. Options include: + - `full_spectrum` + - `brute_force`: A direct approach for spectrum calculation, suitable for smaller systems. +- `cluster_assignment_rule::Dict{Int, L}`: A dictionary mapping Ising graph vertices to clusters. Supported lattice geometries include: + - `super_square_lattice`: Maps linear indices to a 2D square lattice with nearest and next-nearest neighbor interactions. + - `pegasus_lattice`: Supports the Pegasus topology used in quantum annealing systems. + - `zephyr_lattice`: Supports the Zephyr topology used in quantum annealing systems. # Returns: -- `potts_h::LabelledGraph{S, T}`: The Potts Hamiltonian represented as a labelled graph. - -The `potts_hamiltonian` function takes an Ising graph (`ig`) as input and constructs a Potts Hamiltonian by -introducing a natural order in Potts 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. +- `potts_h::LabelledGraph{S, T}`: A labelled graph representing the Potts Hamiltonian, where: + - Nodes correspond to clusters of spins. + - Edges represent interactions between clusters. """ function potts_hamiltonian( ig::IsingGraph, @@ -77,23 +79,25 @@ end """ $(TYPEDSIGNATURES) -Create a Potts Hamiltonian. +Construct a Potts Hamiltonian. -This function constructs a Potts Hamiltonian from an Ising graph by introducing a natural order in Potts Hamiltonian coordinates. +This function converts an Ising graph into a Potts Hamiltonian by clustering Ising spins into groups defined by a specified lattice geometry. Each cluster is assigned a fixed number of states, and inter-cluster interactions are computed based on the structure of the Ising graph. # 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. Number of states are considered when calculating the spectrum. -- `spectrum::Function`: A function for calculating the spectrum of the Potts 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`. +- `ig::IsingGraph`: The input Ising graph, where vertices represent spins and edges represent interactions between them. +- `num_states_cl::Dict{T, Int}`: A dictionary mapping cluster indices to the number of states for each cluster. + If a cluster is not explicitly listed, the function uses the cluster's default basis size. +- `spectrum::Function`: A function for calculating the spectrum of the Potts Hamiltonian for each cluster. + Defaults to `full_spectrum`. Alternatives, such as `brute_force`, may also be provided. +- `cluster_assignment_rule::Dict{Int, T}`: A dictionary mapping Ising graph vertices to clusters. Supported cluster geometries include: + - `super_square_lattice` + - `pegasus_lattice` + - `zephyr_lattice` # Returns: -- `potts_h::LabelledGraph{MetaDiGraph}`: The Potts Hamiltonian represented as a labelled graph. - -The `potts_hamiltonian` function takes an Ising graph (`ig`) as input and constructs a Potts Hamiltonian -by introducing a natural order in Potts Hamiltonian coordinates. It allows you to specify the number of -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. +- `potts_h::LabelledGraph{S, T}`: A labelled graph representing the Potts Hamiltonian, with: + - Nodes: Corresponding to spin clusters, including their spectrum and configuration data. + - Edges: Representing inter-cluster interactions. """ function potts_hamiltonian( @@ -147,24 +151,27 @@ end """ $(TYPEDSIGNATURES) -Create a Potts Hamiltonian with optional cluster sizes. +Construct a Potts Hamiltonian with default cluster sizes. -This function constructs a Potts Hamiltonian from an Ising graph by introducing a natural order in Potts Hamiltonian coordinates. +This function converts an Ising graph into a Potts Hamiltonian using a specified cluster assignment rule. +By default, this version of the function does not truncate cluster states, as it assigns the full basis size for each cluster during spectrum calculation. +It is useful when no custom cluster sizes are required. # Arguments: -- `ig::IsingGraph`: The Ising graph representing the spin system. -- `spectrum::Function`: A function for calculating the spectrum of the Potts 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`. +- `ig::IsingGraph`: The input Ising graph, where vertices represent spins and edges represent interactions. +- `spectrum::Function`: A function for calculating the spectrum of the Potts Hamiltonian. Options include: + - `full_spectrum` (default): Computes the complete spectrum for all cluster configurations. + - `brute_force`: Suitable for smaller systems, uses direct enumeration to calculate the spectrum. +- `cluster_assignment_rule::Dict{Int, T}`: A dictionary mapping Ising graph vertices to clusters. Supported cluster geometries include: + - `super_square_lattice` + - `pegasus_lattice` + - `zephyr_lattice` # Returns: -- `potts_h::LabelledGraph{MetaDiGraph}`: The Potts Hamiltonian represented as a labelled graph. - -The `potts_hamiltonian` function takes an Ising graph (`ig`) as input and constructs a Potts Hamiltonian -by introducing a natural order in Potts 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 `potts_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`. +- `potts_h::LabelledGraph{MetaDiGraph}`: A labelled graph representing the Potts Hamiltonian, where: + - Nodes: Correspond to clusters of spins, with properties such as the spectrum and configuration details. + - Edges: Capture inter-cluster interactions, including coupling strengths and energy terms. + """ function potts_hamiltonian( ig::IsingGraph; @@ -210,12 +217,9 @@ end """ $(TYPEDSIGNATURES) +Decode a Potts Hamiltonian clustered states into Ising spin states. -TODO: check the order consistency over external packages. - -Decode a Potts Hamiltonian state into Ising graph spin values. - -This function decodes a state from a Potts Hamiltonian into Ising graph spin values and +This function decodes a state encoded in a Potts Hamiltonian language into states compatible with binary Ising graph and returns a dictionary mapping each Ising graph vertex to its corresponding spin value. # Arguments: @@ -415,26 +419,6 @@ function exact_cond_prob( sum(prob[findall([all(s[k] == v for (k, v) ∈ target_state) for s ∈ states])]) end -""" -$(TYPEDSIGNATURES) - -Truncate a Potts Hamiltonian based on specified states. - -This function truncates a given Potts Hamiltonian by selecting a subset of states for each cluster based on the provided `states` dictionary. -The resulting truncated Hamiltonian contains only the selected states for each cluster. - -# Arguments: -- `potts_h::LabelledGraph{S, T}`: The Potts Hamiltonian represented as a labeled graph. -- `states::Dict`: A dictionary specifying the states to be retained for each cluster. - -# Returns: -- `new_potts_h::LabelledGraph{MetaDiGraph}`: The truncated Potts Hamiltonian with reduced states. - -The function creates a new Potts Hamiltonian `new_potts_h` with the same structure as the input `potts_h`. -It then updates the spectrum of each cluster in `new_potts_h` by selecting the specified states from the original spectrum. -Additionally, it updates the interactions and projectors between clusters based on the retained states. -The resulting `new_potts_h` represents a truncated version of the original Hamiltonian. -""" function truncate_potts_hamiltonian(potts_h::LabelledGraph{S,T}, states::Dict) where {S,T} new_potts_h = LabelledGraph{MetaDiGraph}(vertices(potts_h)) @@ -479,6 +463,25 @@ function truncate_potts_hamiltonian(potts_h::LabelledGraph{S,T}, states::Dict) w new_potts_h end +""" +$(TYPEDSIGNATURES) + +Construct a Potts Hamiltonian for a Random Markov Field (RMF) model. + +This function creates a Potts Hamiltonian from a Random Markov Field specified in an OpenGM-compatible file. +It maps the RMF variables and their pairwise interactions onto a 2D grid structure, constructing the corresponding Potts Hamiltonian using a super square lattice representation. +The function supports optional resizing of the grid dimensions. + +# Arguments +- `fname::String`: Path to the OpenGM-compatible file containing the RMF definition. This file includes functions, factors, and variable dimensions. +- `Nx::Union{Integer, Nothing}`: (Optional) Number of columns in the 2D grid. If `nothing`, the dimensions are inferred from the file. +- `Ny::Union{Integer, Nothing}`: (Optional) Number of rows in the 2D grid. If `nothing`, the dimensions are inferred from the file. + +# Returns +- `potts_h::LabelledGraph{MetaDiGraph}`: A labelled graph representing the Potts Hamiltonian, where: + - Vertices correspond to individual clusters in the super square lattice. + - Edges represent interactions between clusters, annotated with energy and projector information. +""" function potts_hamiltonian( fname::String, Nx::Union{Integer,Nothing} = nothing, diff --git a/src/truncate.jl b/src/truncate.jl index df29241..6d24ad5 100644 --- a/src/truncate.jl +++ b/src/truncate.jl @@ -92,17 +92,20 @@ $(TYPEDSIGNATURES) Truncate a Potts Hamiltonian based on 2-site belief propagation states. -This function truncates a Potts Hamiltonian by considering 2-site belief propagation states and selecting the most probable states -to keep. It computes the beliefs for all 2-site combinations and selects the states that maximize the probability. +This function truncates the state space of a Potts Hamiltonian by leveraging 2-site belief propagation. +In certain geometries, such as Pegasus or Zephyr, clusters in the Potts Hamiltonian are further divided into smaller sub-clusters. +This function computes beliefs for the entire 2-site cluster and selects states that maximize the overall probability in a cluster. # Arguments: - `potts_h::LabelledGraph{S, T}`: The Potts 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). +- `beliefs::Dict`: A dictionary where keys are clusters (vertices) and values are the beliefs. +- `num_states::Int`: The maximum number of most probable states to retain for each cluster. +- `result_folder::String (optional)`: Path to the folder where truncated states will be saved. Default is `"results_folder"`. +- `inst::String (optional)`: Instance name for saving or loading results. Default is `"inst"`. +- `beta::Real (optional)`: The inverse temperature parameter. Default is `1.0`. # Returns: -- `LabelledGraph{S, T}`: A truncated Potts Hamiltonian. +- `LabelledGraph{S, T}`: A Potts Hamiltonian with reduced state space, preserving only the most probable states. """ function truncate_potts_hamiltonian_2site_BP( potts_h::LabelledGraph{S,T}, @@ -171,6 +174,26 @@ function select_numstate_best(E, sx, num_states) end end +""" +$(TYPEDSIGNATURES) + +Truncate the Potts Hamiltonian using belief propagation or precomputed states. + +This function reduces the dimensionality of a given Potts Hamiltonian by truncating its states. +The process is guided by the Loopy Belief Propagation (LBP) algorithm, which estimates the marginal probabilities of states in the Potts model. If precomputed states are available, they are loaded from the specified result folder to skip recomputation. + +# Arguments: +- `potts_h`: The input Potts Hamiltonian, represented as a labelled graph. +- `β::Float64`: The inverse temperature parameter controlling the distribution of states. +- `cs::Int`: The maximum number of states retained per cluster after truncation. +- `result_folder::String`: The folder path where results are stored or loaded. +- `inst::String`: The instance name used to identify stored results. +- `tol::Float64`: (Optional) Convergence tolerance for the belief propagation algorithm. Default is `1e-6`. +- `iter::Int`: The maximum number of iterations for the belief propagation algorithm. + +# Returns: +- `potts_h`: A truncated Potts Hamiltonian with reduced state space, preserving the most relevant states per cluster. +""" function truncate_potts_hamiltonian( potts_h, β,