From 4008b7b5545a8d5f304d80db0300697b09f4bc3c Mon Sep 17 00:00:00 2001 From: annamariadziubyna <73058800+annamariadziubyna@users.noreply.github.com> Date: Fri, 17 Nov 2023 07:34:33 +0100 Subject: [PATCH] add the docs --- docs/make.jl | 7 ++- docs/src/api.md | 12 ---- docs/src/bp.md | 9 +++ docs/src/clh.md | 25 +++++++++ docs/src/ising.md | 25 +++++++++ docs/src/lattice.md | 90 ++++++++++++++++++++++++++++++ docs/src/userguide.md | 124 +----------------------------------------- 7 files changed, 156 insertions(+), 136 deletions(-) create mode 100644 docs/src/bp.md create mode 100644 docs/src/clh.md create mode 100644 docs/src/ising.md create mode 100644 docs/src/lattice.md diff --git a/docs/make.jl b/docs/make.jl index fbb6101..c54d524 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,9 +1,12 @@ using Documenter, SpinGlassNetworks _pages = [ - "Introduction" => "index.md", "User guide" => "userguide.md", - "API Reference" => "api.md" + "Lattice geometries" => "lattice.md", + "Ising graph" => "ising.md", + "Clustered hamiltonian" => "clh.md", + "Local dimensional reduction" => "bp.md", + "API Reference for auxiliary functions" => "api.md" ] # ============================ diff --git a/docs/src/api.md b/docs/src/api.md index 3e134c7..342a2fe 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -8,7 +8,6 @@ CurrentModule = SpinGlassNetworks ## Ising Graphs ```@docs -ising_graph inter_cluster_edges prune couplings @@ -17,7 +16,6 @@ couplings ## Clustered Hamiltonian ```@docs split_into_clusters -clustered_hamiltonian decode_clustered_hamiltonian_state rank_reveal energy @@ -28,22 +26,13 @@ exact_cond_prob truncate_clustered_hamiltonian ``` -## Lattice -```@docs -super_square_lattice -pegasus_lattice -zephyr_lattice -``` - ## Belief propagation ```@docs local_energy interaction_energy get_neighbors -belief_propagation MergedEnergy update_message -clustered_hamiltonian_2site merge_vertices_cl_h projector SparseCSC @@ -68,7 +57,6 @@ brute_force ## Truncate ```@docs truncate_clustered_hamiltonian_1site_BP -truncate_clustered_hamiltonian_2site_BP truncate_clustered_hamiltonian_2site_energy select_numstate_best ``` diff --git a/docs/src/bp.md b/docs/src/bp.md new file mode 100644 index 0000000..918f826 --- /dev/null +++ b/docs/src/bp.md @@ -0,0 +1,9 @@ +## 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. + +```@docs +clustered_hamiltonian_2site +belief_propagation +truncate_clustered_hamiltonian_2site_BP +``` \ No newline at end of file diff --git a/docs/src/clh.md b/docs/src/clh.md new file mode 100644 index 0000000..894df6d --- /dev/null +++ b/docs/src/clh.md @@ -0,0 +1,25 @@ +# 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. + +```@docs +clustered_hamiltonian +``` + +## Simple example + +```@example +using SpinGlassNetworks + +# Prepare simple instance +instance = Dict((1, 1) => 1.0, (2, 2) => 0.5, (3, 3) => -0.25, +(1, 2) => -1.0, (2, 3) => 1.0) +ig = ising_graph(instance) + +# Create clustered Hamiltonian. +cl_h = clustered_hamiltonian( + ig, + cluster_assignment_rule = super_square_lattice((3, 1, 1)) +) +``` \ No newline at end of file diff --git a/docs/src/ising.md b/docs/src/ising.md new file mode 100644 index 0000000..eb81764 --- /dev/null +++ b/docs/src/ising.md @@ -0,0 +1,25 @@ +# Introduction + +The Ising model is a mathematical model used to describe the behavior of interacting particles, such as atoms or molecules, in a magnetic field. In the Ising model, each particle is represented as a binary variable $s_i$ that can take on the values of either +1 or -1. The total energy of the system is given by the Hamiltonian: + +$$H = \sum_{(i,j) \in \mathcal{E}} J_{ij} s_i s_j + \sum_{i} h_i s_i$$ + +where $J_{ij}$ is the coupling constant between particles $i$ and $j$, $h_i$ is the external magnetic field at particle $i$, and the sum is taken over all pairs of particles and all particles in the system $\mathcal{E}$, respectively. + +```@docs +ising_graph +``` + +## Simple example +```@example +using SpinGlassNetworks +# Create Ising instance +instance = Dict((1, 1) => 1.0, (2, 2) => 0.5, (3, 3) => -0.25, +(1, 2) => -1.0, (2, 3) => 1.0) + +# Generate Ising graph +ig = ising_graph(instance) + +# View graph properties +@show biases(ig), couplings(ig) +``` \ No newline at end of file diff --git a/docs/src/lattice.md b/docs/src/lattice.md new file mode 100644 index 0000000..ac7698f --- /dev/null +++ b/docs/src/lattice.md @@ -0,0 +1,90 @@ +## Lattice +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. + +## Super square lattice +The `super_square_lattice` geometry represents a square lattice where unit cells consist of multiple spins, offering the unique feature of accommodating diagonal next-nearest-neighbor interactions. This geometry allows for a nuanced exploration of spin interactions beyond the traditional square lattice framework. + +```@docs +super_square_lattice +``` + +```@example +using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs + +# load Chimera instance and create Ising graph +instance = "$(@__DIR__)/../../src/instances/square_diagonal/5x5/diagonal.txt" +ig = ising_graph(instance) + +# Loaded instance is zephyr graph +m = 5 +n = 5 +t = 4 + +cl_h = clustered_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))) +``` + +## Pegasus graphs +The Pegasus graph is a type of graph architecture used in quantum computing systems, particularly in the quantum annealing machines developed by D-Wave Systems. It is designed to provide a grid of qubits with specific connectivity patterns optimized for solving certain optimization problems. Futer details can be found [here](https://docs.dwavesys.com/docs/latest/c_gs_4.html#pegasus-graph). +```@raw html + +``` + +```@docs +pegasus_lattice +``` + +```@example +using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs + +# load Chimera 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 +m = 3 +n = 3 +t = 3 + +cl_h = clustered_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))) +``` + + +## Zephyr graphs +The Zephyr graph is a type of graph architecture used in quantum computing systems, particularly in the quantum annealing machines developed by D-Wave Systems. Futer details can be found [here](https://docs.dwavesys.com/docs/latest/c_gs_4.html#zephyr-graph). +```@raw html + +``` + +```@docs +zephyr_lattice +``` + +```@example +using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs + +# load Chimera 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 +m = 6 +n = 6 +t = 4 + +cl_h = clustered_hamiltonian( + ig, + cluster_assignment_rule = zephyr_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))) +``` \ No newline at end of file diff --git a/docs/src/userguide.md b/docs/src/userguide.md index acdd7f6..ebfd29f 100644 --- a/docs/src/userguide.md +++ b/docs/src/userguide.md @@ -1,125 +1,5 @@ # Introduction -This section provides examples of how to use the 'ising_graph' function to generate an Ising model graph and the 'clustered_hamiltonian' function to convert the Ising graph into a clustered Hamiltonian. -# Ising Graph -The Ising model is a mathematical model used to describe the behavior of interacting particles, such as atoms or molecules, in a magnetic field. In the Ising model, each particle is represented as a binary variable $s_i$ that can take on the values of either +1 or -1. The total energy of the system is given by the Hamiltonian: +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. -$$H = \sum_{(i,j) \in \mathcal{E}} J_{ij} s_i s_j + \sum_{i} h_i s_i$$ - -where $J_{ij}$ is the coupling constant between particles $i$ and $j$, $h_i$ is the external magnetic field at particle $i$, and the sum is taken over all pairs of particles and all particles in the system $\mathcal{E}$, respectively. - - -## Simple example -```@example -using SpinGlassNetworks -# Create Ising instance -instance = Dict((1, 1) => 1.0, (2, 2) => 0.5, (3, 3) => -0.25, -(1, 2) => -1.0, (2, 3) => 1.0) - -# Generate Ising graph -ig = ising_graph(instance) - -# View graph properties -@show biases(ig), couplings(ig) -``` - -## Generalisation - -The 'ising_graph' function is quite general function. One can easly convert instance into another hamiltonian convention, ex. -```math -H = - \sum_{(i,j) \in \mathcal{E}} J_{ij} s_i s_j - \mu \sum_{i} h_i s_i -``` - -'ising_graph' also allows for building other spin system, not only spin-``\frac{1}{2}`` system. For example one may build chain where sites allows for 3 spin values. - -```@example -using SpinGlassNetworks - -# Create spin chain instance -instance = Dict((1, 1) => 1.0, (2, 2) => 0.5, (3, 3) => -0.25, -(1, 2) => -1.0, (2, 3) => 1.0) - -rank_override = Dict(1 => 3, 2 => 3, 3 => 3) - -sg = ising_graph(instance, rank_override=rank_override) - -# see ranks of each site -rank_vec(sg) -``` - -# Clustered Hamiltonian - -A clustered Hamiltonian is a graphical representation that allows for a convenient and intuitive way to describe the structure of a tensor network. - -A clustered Hamiltonian consists of two types of nodes: variable nodes and factor nodes. Variable nodes represent the tensors in the tensor network, and factor nodes represent the operations that are applied to those tensors. - -Each variable node in the clustered Hamiltonian corresponds to a tensor in the tensor network, and each factor node corresponds to a tensor contraction or operation that is applied to one or more of those tensors. The edges between the nodes in the clustered Hamiltonian represent the indices that are shared between the corresponding tensors in the tensor network. - -## Simple example - -```@example -using SpinGlassNetworks - -# Prepare simple instance -instance = Dict((1, 1) => 1.0, (2, 2) => 0.5, (3, 3) => -0.25, -(1, 2) => -1.0, (2, 3) => 1.0) -ig = ising_graph(instance) - -# Create clustered Hamiltonian. -cl_h = clustered_hamiltonian( - ig, - cluster_assignment_rule = super_square_lattice((3, 1, 1)) -) -``` - -## Pegasus graphs -The Pegasus graph is a type of graph architecture used in quantum computing systems, particularly in the quantum annealing machines developed by D-Wave Systems. It is designed to provide a grid of qubits with specific connectivity patterns optimized for solving certain optimization problems. Futer details can be found [here](https://docs.dwavesys.com/docs/latest/c_gs_4.html#pegasus-graph). -```@raw html - -``` - -```@example -using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs - -# load Chimera 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 -m = 3 -n = 3 -t = 3 - -cl_h = clustered_hamiltonian( - ig, - cluster_assignment_rule = pegasus_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))) -``` - - -## Zephyr graphs -The Zephyr graph is a type of graph architecture used in quantum computing systems, particularly in the quantum annealing machines developed by D-Wave Systems. Futer details can be found [here](https://docs.dwavesys.com/docs/latest/c_gs_4.html#zephyr-graph). -```@raw html - -``` -```@example -using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs - -# load Chimera 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 -m = 6 -n = 6 -t = 4 - -cl_h = clustered_hamiltonian( - ig, - cluster_assignment_rule = zephyr_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))) -``` \ No newline at end of file +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.