From 3830181d9d496e2d9f13f5a93498255ad085dc8c Mon Sep 17 00:00:00 2001 From: tomsmierz <53766192+tomsmierz@users.noreply.github.com> Date: Sun, 12 Mar 2023 23:05:01 +0100 Subject: [PATCH] Ad/docs (#20) * add docs * add DocStringExtensions * fixed bug * work in progress * Work in Progress * Work in Progress * Work in progress * somewhat done --------- Co-authored-by: annamariadziubyna <73058800+annamariadziubyna@users.noreply.github.com> Co-authored-by: tomsmierz --- docs/make.jl | 14 ++++++++++++ docs/src/api.md | 12 ++++++++++ docs/src/guide.md | 43 +++++++++++++++++++++++++++++++++++ docs/src/index.md | 3 +++ src/PEPS.jl | 6 +++++ src/search.jl | 45 +++++++++++++++++++++++++++++++++++++ test/search_full_chimera.jl | 2 +- 7 files changed, 124 insertions(+), 1 deletion(-) create mode 100644 docs/make.jl create mode 100644 docs/src/api.md create mode 100644 docs/src/guide.md create mode 100644 docs/src/index.md diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 00000000..b457fc0c --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,14 @@ +using Documenter, SpinGlassEngine + +_pages = [ + "Introduction" => "index.md", + "User Guide" => "guide.md", + "API Reference" => "api.md" +] +# ============================ + +makedocs( + sitename="SpinGlassEngine", + modules = [SpinGlassEngine], + pages = _pages + ) \ No newline at end of file diff --git a/docs/src/api.md b/docs/src/api.md new file mode 100644 index 00000000..22c361a4 --- /dev/null +++ b/docs/src/api.md @@ -0,0 +1,12 @@ +# Library + +--- + +## Core + +```@docs +Solution +Solution() +low_energy_spectrum +PEPSNetwork +``` \ No newline at end of file diff --git a/docs/src/guide.md b/docs/src/guide.md new file mode 100644 index 00000000..249e7174 --- /dev/null +++ b/docs/src/guide.md @@ -0,0 +1,43 @@ +# Introduction +We consider a classical Ising Hamiltonian +```math +E = \sum_{ \in \mathcal{E}} J_{ij} s_i s_j + \sum_j h_i s_j. +``` +where ``s`` is a configuration of ``N`` classical spins taking values ``s_i = \pm 1`` +and ``J_{ij}, h_i \in \mathbb{R}`` are input parameters of a given problem instance. +Nonzero couplings ``J_{ij}`` form a graph ``\mathcal{E}``. Edges of ``\mathcal{E}`` form a quasi-two-dimensional structure. In this package we focus in particular on the [Chimera](https://docs.dwavesys.com/docs/latest/c_gs_4.html#chimera-graph) graph with up to 2048 spins. + + +## Finding structure of low energy states +Below we describe simple Ising chain spin system with open boundary condition. The system has three spins with couplings ``J_{12} = -1.0`` and``J_{23} = 1.0``. Additionaly there are local fields ``h_1 = 0.5``, ``h_2 = 0.75`` and ``h_3 = -0.25``. + +We can calculate spectrum using `SpinGlassPEPS`. First we create graph (called Ising graph) which corespond to given Ising system. Then from this graph we create PEPS tensor network. Lastly we define model's parameters and control parameters such as `num_states` - maximal number of low energy states to be found. Then we can use function `low_energy_spectrum` to find desired low energy spectrum. + + +```@example +using SpinGlassEngine, SpinGlassTensors, SpinGlassNetworks, SpinGlassPEPS, MetaGraphs + +# Create instance and coresponding factor graph. Details can be +# found in SpinGlassNetworks documentation. +instance = Dict((1, 1) => 0.5, (2, 2) => 0.75, (3, 3) => -0.25, (1, 2) => -1.0, (2, 3) => 1.0) +ig = ising_graph(instance) +fg = factor_graph( + ig, + cluster_assignment_rule = super_square_lattice((3, 1, 1)), + ) + +# Define inverse temperature for gibbs distribution used in tensor network +# contraction. Details can be found in SpinGlassEngine documentation +β = 1.0 + +# Create PEPS network +peps = PEPSNetwork(3, 1, fg, rotation(0), β = β, bond_dim = 32) + +# Decide number of states we wane +num_states = 3 + +# Solve model +sol = low_energy_spectrum(peps, num_states) +@show sol.states, sol.energies + +``` diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 00000000..9c5d8292 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,3 @@ +# SpinGlassEngine + +A [Julia](http://julialang.org) package for finding low energy spectrum of Ising spin systems. Part of [SpinGlassPEPS](https://github.com/euro-hpc-pl/SpinGlassPEPS.jl) package. \ No newline at end of file diff --git a/src/PEPS.jl b/src/PEPS.jl index 8ea3a12f..82813852 100644 --- a/src/PEPS.jl +++ b/src/PEPS.jl @@ -2,6 +2,11 @@ export PEPSNetwork, generate_boundary, node_from_index, conditional_probability const IntOrRational = Union{Int,Rational{Int}} +""" + PEPSNetwork + +Structure that stores PEPS tensor network +""" struct PEPSNetwork <: AbstractGibbsNetwork{NTuple{2,Int},NTuple{2,Int}} factor_graph::LabelledGraph{T,NTuple{2,Int}} where {T} network_graph::LabelledGraph{S,NTuple{2,Int}} where {S} @@ -21,6 +26,7 @@ struct PEPSNetwork <: AbstractGibbsNetwork{NTuple{2,Int},NTuple{2,Int}} layers_left_env::NTuple{K,IntOrRational} where {K} layers_right_env::NTuple{L,IntOrRational} where {L} + function PEPSNetwork( m::Int, n::Int, diff --git a/src/search.jl b/src/search.jl index 10cecb72..ece063d9 100644 --- a/src/search.jl +++ b/src/search.jl @@ -1,6 +1,21 @@ export AbstractGibbsNetwork, low_energy_spectrum, branch_state, bound_solution, merge_branches, Solution, Memoize + +""" +Store results from branch-and-bound search. + +# Fields + + energies::Vector{Float64}: A vector storing the energies of the system. + states::Vector{Vector{Int}}: A vector storing states of the system. These + are states of factor graph representation of the system. + probabilities::Vector{Float64}: A vector storing representing the probabilities + of each state in the states field. Probabilities are kept as `log2`. + degeneracy::Vector{Int}: A vector storing the degeneracy of each energy level in the energies field. + largest_discarded_probability::Float64: A value representing the largest probability that was discarded during the branch-and-bound search . + +""" struct Solution energies::Vector{Float64} states::Vector{Vector{Int}} @@ -9,6 +24,11 @@ struct Solution largest_discarded_probability::Float64 end +""" + Solution() + +Creates empty `Solution` +""" Solution() = Solution([0.0], [[]], [1.0], [1], -Inf) @@ -118,6 +138,31 @@ end #TODO: incorporate "going back" move to improve alghoritm +""" + low_energy_spectrum( + network::AbstractGibbsNetwork, + max_states::Int, + merge_strategy = no_merge, + ) + +Search for the low-energy spectrum on a quasi-2d graph. + +# Details +Compute the low energy spectrum of an Ising system represented +by a `network` object, using a branch-and-bound search algorithm with a +maximum number of `max_states` states and an optional `merge_strategy`. + +# Arguments +- `network::AbstractGibbsNetwork`: PEPS tesnor network representing Ising system. +- `max_states::Int`: The maximum number of states to use in the search algorithm. +- `merge_strategy=no_merge`: An optional argument that specifies the strategy to use + when merging states. The default is no_merge, which means no merging will be performed. + +Return value + +The function returns a `Solution` object representing the low energy spectrum of the system. + +""" function low_energy_spectrum( network::AbstractGibbsNetwork, max_states::Int, diff --git a/test/search_full_chimera.jl b/test/search_full_chimera.jl index ccbd312d..0161d870 100644 --- a/test/search_full_chimera.jl +++ b/test/search_full_chimera.jl @@ -24,7 +24,7 @@ function bench() #for transform ∈ all_lattice_transformations peps = PEPSNetwork(m, n, fg, rotation(0), β = β, bond_dim = 32) - update_gauges!(peps, :rand) + kupdate_gauges!(peps, :rand) @time sol = low_energy_spectrum(peps, num_states)#, merge_branches(peps, 1.0)) println(sol.energies[1:1]) end