diff --git a/docs/src/algorithm.md b/docs/src/algorithm.md index 47e6d97..e9cc3d2 100644 --- a/docs/src/algorithm.md +++ b/docs/src/algorithm.md @@ -11,7 +11,7 @@ where $\underline{s}_N$ denotes a particular configuration of $N$ binary variabl We assume that graph $\mathcal{E}$ forms a quasi-2D lattice. In real life applications such graphs have large unit cells approaching 24 spins. `SpinGlassPEPS.jl` allows for unit cells containing multiple spins. !!! info - More information on lattice geometries you can find in section Lattice Geometries (TODO: link). + More information on lattice geometries you can find in section [Lattice Geometries](sgn/lattice.md). ```@raw html @@ -32,7 +32,7 @@ We represent the probability distribution as a PEPS tensor network. ```math p(\underline{x}_{\bar{N}}) = \frac{1}{Z} \exp{(-\beta H(\underline{x}_{\bar{N}}))} ``` -where $Z$ is a partition function and $\beta$ is inverse temperature. Once the PEPS tensor network is constructed, the probability distribution can be obtained by approximately contracting the tensor network, which is described in more details in subsection Tensor network contractions for optimization problems (TODO: link). +where $Z$ is a partition function and $\beta$ is inverse temperature. Once the PEPS tensor network is constructed, the probability distribution can be obtained by approximately contracting the tensor network, which is described in more details in subsection [Tensor network contractions for optimization problems](#Tensor-network-contractions-for-optimization-problems). Subsequently, we select only the configurations with the highest marginal probabilities ```math p(\underline{x}_{n+1}) = p(x_{n+1} | \underline{x}_{n}) \times p(\underline{x}_{n}) @@ -44,7 +44,6 @@ By employing branch and bound search strategy iteratively row after row, we addr ```@raw html ``` - ## Tensor network contractions for optimization problems Branch and bound search relies on the calculation of conditional probabilities. To that end, we use tensor network techniques. Conditional probabilities are obtained by contracting a PEPS tensor network, which, although an NP-hard problem, can be computed approximately. The approach utilized is boundary MPS-MPO, which involves contracting a tensor network row by row and truncating the bond dimension. diff --git a/docs/src/examples_old.md b/docs/src/examples_old.md deleted file mode 100644 index 5027071..0000000 --- a/docs/src/examples_old.md +++ /dev/null @@ -1,331 +0,0 @@ -# Introduction -In this section, we will introduce two illustrative examples to highlight the effectiveness of the software. The first example will delve into a classical Ising problem commonly encountered in research, while the second will focus on an optimization problem related to Random Markov Fields. These examples serve as practical demonstrations of `SpinGlassPEPS.jl` in action, providing valuable insights into the software's capabilities and showcasing its utility across a wide range of scenarios. -# Ising type optimization problems -Ising type optimization problems with the cost function: - -$$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 spins $i$ and $j$, $s_i$, $s_j$ can take on the values of either +1 or -1, $h_i$ is the external magnetic field at spin $i$, and the sum is taken over all pairs of spins and all spins in the system $\mathcal{E}$, respectively. - -## Ground state search on super square lattice - -In this example, we demonstrate how to use the `SpinGlassPEPS.jl` package to perform a low-energy spectrum search for a Spin Glass Hamiltonian defined on a square lattice with next nearest neighbors interactions on 100 spins. -```@raw html - -``` -The package is used to explore various strategies for solving the problem, and it provides functionalities for performing Hamiltonian clustering, belief propagation, and low-energy spectrum searches using different MPS (Matrix Product State) strategies. - -First, we set up the problem by defining the lattice and specifying various parameters such as temperature (β), bond dimension, and search parameters. We also create a clustered Hamiltonian using the specified lattice and perform clustering calculations. - -Next, we select the MPS strategy (in this case, Zipper) and other parameters for the network contractor. We create a PEPS (Projected Entangled Pair State) network and initialize the contractor with this network, along with the specified parameters. - -Finally, we perform a low-energy spectrum search using the initialized contractor, exploring different branches of the search tree. The example showcases how SpinGlassPEPS can be utilized to find the lowest energy configurations for a Spin Glass system. - - -```@example -using SpinGlassEngine, SpinGlassTensors, SpinGlassNetworks, SpinGlassPEPS -using SpinGlassExhaustive -using Logging -using LightGraphs -using LinearAlgebra -using TensorCast -using MetaGraphs -using Statistics - -function my_brute_force(ig::IsingGraph; num_states::Int) - brute_force(ig, onGPU ? :GPU : :CPU, num_states=num_states) -end - -function bench(instance::String) - m, n, t = 5, 5, 4 - onGPU = true - - β = 1.0 - bond_dim = 12 - δp = 1E-4 - num_states = 20 - - ig = ising_graph(instance) - cl_h = clustered_hamiltonian( - ig, - spectrum = full_spectrum, - cluster_assignment_rule=super_square_lattice((m, n, t)) - ) - params = MpsParameters(bond_dim, 1E-8, 10) - search_params = SearchParameters(num_states, δp) - Gauge = NoUpdate - graduate_truncation = :graduate_truncate - for Strategy ∈ (SVDTruncate, MPSAnnealing, Zipper), transform ∈ all_lattice_transformations - for Layout ∈ (GaugesEnergy, EnergyGauges, EngGaugesEng), Sparsity ∈ (Dense, Sparse) - net = PEPSNetwork{SquareCrossSingleNode{Layout}, Sparsity}(m, n, cl_h, transform) - ctr = MpsContractor{Strategy, Gauge}(net, [β/8, β/4, β/2, β], graduate_truncation, params; onGPU=onGPU) - # sol_peps, s = low_energy_spectrum(ctr, search_params, merge_branches(ctr)) - clear_memoize_cache() - end - end -end - -bench("$(@__DIR__)/../src/instances/square_diagonal/5x5/diagonal.txt") -``` -## Ground state search on Pegasus lattice -In this example, we demonstrate how to use the `SpinGlassPEPS.jl` package to perform a low-energy spectrum search for a Spin Glass Hamiltonian defined on a D-Wave Pegasus lattice with 216 spins and 1324 couplings. -```@raw html - -``` - -```@example -using SpinGlassEngine, SpinGlassTensors, SpinGlassNetworks, SpinGlassPEPS -using SpinGlassExhaustive -using Logging -using LightGraphs -using LinearAlgebra -using TensorCast -using MetaGraphs -using Statistics - -function my_brute_force(ig::IsingGraph; num_states::Int) - brute_force(ig, onGPU ? :GPU : :CPU, num_states=num_states) -end - -m = 3 -n = 3 -t = 3 - -onGPU = true -β = 0.5 -bond_dim = 8 -DE = 16.0 -δp = 1E-5*exp(-β * DE) -num_states = 128 - -VAR_TOL = 1E-16 -MS = 0 -TOL_SVD = 1E-16 -ITERS_SVD = 1 -ITERS_VAR = 1 -DTEMP_MULT = 2 - -ig = ising_graph("$(@__DIR__)/../src/instances/pegasus_random/P4/RAU/001_sg.txt") - -cl_h = clustered_hamiltonian( - ig, - spectrum=full_spectrum, - cluster_assignment_rule=pegasus_lattice((m, n, t)) -) - -params = MpsParameters(bond_dim, VAR_TOL, MS, TOL_SVD, ITERS_SVD, ITERS_VAR, DTEMP_MULT) -search_params = SearchParameters(num_states, δp) - -# Solve using PEPS search -energies = Vector{Float64}[] -Strategy = Zipper # MPSAnnealing # SVDTruncate -Sparsity = Sparse #Dense -Layout = GaugesEnergy -Gauge = NoUpdate - -net = PEPSNetwork{SquareCrossDoubleNode{Layout}, Sparsity}(m, n, cl_h, rotation(0)) -ctr = MpsContractor{Strategy, Gauge}(net, [β/6, β/3, β/2, β], :graduate_truncate, params; onGPU=onGPU) - -# sol, s = low_energy_spectrum(ctr, search_params, merge_branches(ctr)) -# println("Lowest energy found: ", sol.energies) - -``` - -## Droplet search on Pegasus lattice -In this example, we demonstrate how to use the `SpinGlassPEPS.jl` package to perform a low-energy spectrum search for a Spin Glass Hamiltonian defined on a D-Wave Pegasus lattice with 216 spins and 1324 couplings. - - -```@example -using SpinGlassEngine, SpinGlassTensors, SpinGlassNetworks, SpinGlassPEPS -using SpinGlassExhaustive -using Logging -using LightGraphs -using LinearAlgebra -using TensorCast -using MetaGraphs -using Statistics - -function my_brute_force(ig::IsingGraph; num_states::Int) - brute_force(ig, onGPU ? :GPU : :CPU, num_states=num_states) -end - -m = 3 -n = 3 -t = 3 - -onGPU = true -β = 0.5 -bond_dim = 8 -DE = 16.0 -δp = 1E-5*exp(-β * DE) -num_states = 128 -energy_cutoff = 1 -hamming_cutoff = 20 -VAR_TOL = 1E-16 -MS = 0 -TOL_SVD = 1E-16 -ITERS_SVD = 1 -ITERS_VAR = 1 -DTEMP_MULT = 2 - -ig = ising_graph("$(@__DIR__)/../src/instances/pegasus_random/P4/RAU/001_sg.txt") - -cl_h = clustered_hamiltonian( - ig, - spectrum=full_spectrum, - cluster_assignment_rule=pegasus_lattice((m, n, t)) -) - -params = MpsParameters(bond_dim, VAR_TOL, MS, TOL_SVD, ITERS_SVD, ITERS_VAR, DTEMP_MULT) -search_params = SearchParameters(num_states, δp) - -# Solve using PEPS search -energies = Vector{Float64}[] -Strategy = Zipper # MPSAnnealing # SVDTruncate -Sparsity = Sparse #Dense -Layout = GaugesEnergy -Gauge = NoUpdate - -net = PEPSNetwork{SquareCrossDoubleNode{Layout}, Sparsity}(m, n, cl_h, rotation(0)) -ctr = MpsContractor{Strategy, Gauge}(net, [β/6, β/3, β/2, β], :graduate_truncate, params; onGPU=onGPU) - -# sol, s = low_energy_spectrum(ctr, search_params, merge_branches(ctr, :nofit, SingleLayerDroplets(energy_cutoff, hamming_cutoff, :hamming))) -# println("Lowest energy found: ", sol.energies) - -``` - - -## Ground state search on Pegasus lattice with local dimensional reduction -In this example, we demonstrate how to use the `SpinGlassPEPS.jl` package to perform a low-energy spectrum search for a Spin Glass Hamiltonian defined on a D-Wave Pegasus lattice with 216 spins and 1324 couplings with local dimensional reduction based on Loopy Belief Propagation algorithm. - -```@example -using SpinGlassEngine, SpinGlassTensors, SpinGlassNetworks, SpinGlassPEPS -using SpinGlassExhaustive -using Logging -using LightGraphs -using LinearAlgebra -using TensorCast -using MetaGraphs -using Statistics - -function my_brute_force(ig::IsingGraph; num_states::Int) - brute_force(ig, onGPU ? :GPU : :CPU, num_states=num_states) -end - -m = 3 -n = 3 -t = 3 - -onGPU = true -β = 0.5 -bond_dim = 8 -DE = 16.0 -δp = 1E-5*exp(-β * DE) -num_states = 128 - -VAR_TOL = 1E-16 -MS = 0 -TOL_SVD = 1E-16 -ITERS_SVD = 1 -ITERS_VAR = 1 -DTEMP_MULT = 2 -iter = 1 -cs = 2^10 -ig = ising_graph("$(@__DIR__)/../src/instances/pegasus_random/P4/RAU/001_sg.txt") - -cl_h = clustered_hamiltonian( - ig, - spectrum=full_spectrum, - cluster_assignment_rule=pegasus_lattice((m, n, t)) -) -new_cl_h = clustered_hamiltonian_2site(cl_h, β) -beliefs = belief_propagation(new_cl_h, β; tol=1e-6, iter=iter) -cl_h = truncate_clustered_hamiltonian_2site_BP(cl_h, beliefs, cs; beta=β) - -params = MpsParameters(bond_dim, VAR_TOL, MS, TOL_SVD, ITERS_SVD, ITERS_VAR, DTEMP_MULT) -search_params = SearchParameters(num_states, δp) - -# Solve using PEPS search -energies = Vector{Float64}[] -Strategy = Zipper # MPSAnnealing # SVDTruncate -Sparsity = Sparse #Dense -Layout = GaugesEnergy -Gauge = NoUpdate - -net = PEPSNetwork{SquareCrossDoubleNode{Layout}, Sparsity}(m, n, cl_h, rotation(0)) -ctr = MpsContractor{Strategy, Gauge}(net, [β/6, β/3, β/2, β], :graduate_truncate, params; onGPU=onGPU) - -# sol, s = low_energy_spectrum(ctr, search_params, merge_branches(ctr)) -# println("Lowest energy found: ", sol.energies) - -``` - - -## Ground state search on Zephyr lattice -In this example, we demonstrate how to use the `SpinGlassPEPS.jl` package to perform a low-energy spectrum search for a Spin Glass Hamiltonian defined on a D-Wave Zephyr lattice with 332 spins and 2735 couplings. -```@raw html - -``` - -```@example -using SpinGlassEngine, SpinGlassTensors, SpinGlassNetworks, SpinGlassPEPS -using SpinGlassExhaustive -using Logging -using LightGraphs -using LinearAlgebra -using TensorCast -using MetaGraphs -using Statistics - -function my_brute_force(ig::IsingGraph; num_states::Int) - brute_force(ig, onGPU ? :GPU : :CPU, num_states=num_states) -end - -m = 6 -n = 6 -t = 4 - -onGPU = true -β = 0.5 -bond_dim = 5 -DE = 16.0 -δp = 1E-5*exp(-β * DE) -num_states = 128 - -VAR_TOL = 1E-16 -MS = 0 -TOL_SVD = 1E-16 -ITERS_SVD = 1 -ITERS_VAR = 1 -DTEMP_MULT = 2 - -ig = ising_graph("$(@__DIR__)/../src/instances/zephyr_random/Z3/RAU/001_sg.txt") - -cl_h = clustered_hamiltonian( - ig, - spectrum=full_spectrum, - cluster_assignment_rule=zephyr_lattice((m, n, t)) -) - -params = MpsParameters(bond_dim, VAR_TOL, MS, TOL_SVD, ITERS_SVD, ITERS_VAR, DTEMP_MULT) -search_params = SearchParameters(num_states, δp) - -# Solve using PEPS search -energies = Vector{Float64}[] -Strategy = Zipper # MPSAnnealing # SVDTruncate -Sparsity = Sparse #Dense -Layout = GaugesEnergy -Gauge = NoUpdate - -net = PEPSNetwork{SquareCrossDoubleNode{Layout}, Sparsity}(m, n, cl_h, rotation(0)) -ctr = MpsContractor{Strategy, Gauge}(net, [β/6, β/3, β/2, β], :graduate_truncate, params; onGPU=onGPU) - -# sol, s = low_energy_spectrum(ctr, search_params, merge_branches(ctr)) -# println("Lowest energy found: ", sol.energies) - -``` - -# Random Markov Field optimization problems -Random Markov Field type model on a 2D square lattice with cost function -$$H = \sum_{(i,j) \in \mathcal{E}} E(s_i, s_j) + \sum_{i} E(s_i)$$ -and nearest-neighbour interactions only. \ No newline at end of file diff --git a/docs/src/images/algorithm.png b/docs/src/images/algorithm.png new file mode 100644 index 0000000..65907de Binary files /dev/null and b/docs/src/images/algorithm.png differ diff --git a/docs/src/images/result.png b/docs/src/images/result.png new file mode 100644 index 0000000..626a07e Binary files /dev/null and b/docs/src/images/result.png differ diff --git a/docs/src/images/zipper_final.png b/docs/src/images/zipper_final.png new file mode 100644 index 0000000..206096e Binary files /dev/null and b/docs/src/images/zipper_final.png differ diff --git a/docs/src/index.md b/docs/src/index.md index 9c07c4f..2918912 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -2,7 +2,7 @@ Author = "Krzysztof Domino, Bartłomiej Gardas, Konrad Jałowiecki, Łukasz Pawela, Marek Rams, Anna Dziubyna, Tomasz Śmierzchalski" ``` -# Welcome to SpinGlassPEPS documentation! +# Welcome to SpinGlassPEPS.jl documentation! Welcome to `SpinGlassPEPS.jl`, a open-source Julia package designed for heuristically solving Ising-type optimization problems defined on quasi-2D lattices and Random Markov Fields on 2D rectangular lattices. @@ -13,24 +13,28 @@ Welcome to `SpinGlassPEPS.jl`, a open-source Julia package designed for heuristi ## Overview In this section we will provide a condensed overview of the package. -`SpinGlassPEPS.jl` is a collection of Julia packages bundled together under a single package `SpinGlassPEPS`. It can be installed using the Julia package manager for Julia v1.6 and higher. Inside the Julia REPL, type ] to enter the Pkg REPL mode and then run +`SpinGlassPEPS.jl` is a collection of Julia packages bundled together under a single package `SpinGlassPEPS.jl`. It can be installed using the Julia package manager for Julia v1.6 and higher. Inside the Julia REPL, type ] to enter the Pkg REPL mode and then run ```julia using Pkg; Pkg.add("SpinGlassPEPS") ``` -The package `SpinGlassPEPS` includes: +The package `SpinGlassPEPS.jl` includes: * `SpinGlassTensors.jl` - Package containing all necessary functionalities for creating and operating on tensors. It allows the use of both CPU and GPU. * `SpinGlassNetworks.jl` - Package containing all tools needed to construct a tensor network from a given instance. * `SpinGlassEngine.jl` - Package containing the solver itself and tools focused on finding and operating on droplets. - +```@raw html + +``` ## Our goals `SpinGlassPEPS.jl` was created to heuristically solve Ising-type optimization problems defined on quasi-2D lattices or Random Markov Fields (RMF) on 2D rectangular lattices. This package combines advanced heuristics to address optimization challenges and employs tensor network contractions to compute conditional probabilities to identify the most probable states according to the Gibbs distribution. `SpinGlassPEPS.jl` is a tool for reconstructing the low-energy spectrum of Ising spin glass Hamiltonians and RMF Hamiltonians. Beyond energy computations, the package offers insights into spin configurations, associated probabilities, and retains the largest discarded probability during the branch and bound optimization procedure. Notably, `SpinGlassPEPS.jl` goes beyond ground states, introducing a unique feature for identifying and analyzing spin glass droplets — collective excitations crucial for understanding system dynamics beyond the fundamental ground state configurations. +```@raw html + +``` - -## Citing SpinGlassPEPS -If you use `SpinGlassPEPS` for academic research and wish to cite it, please use the following paper: +## Citing SpinGlassPEPS.jl +If you use `SpinGlassPEPS.jl` for academic research and wish to cite it, please use the following paper: K. Jałowiecki, K. Domino, A. M. Dziubyna, M. M. Rams, B. Gardas and Ł. Pawela, *“SpinGlassPEPS.jl: software to emulate quantum annealing processors”* diff --git a/docs/src/intro.md b/docs/src/intro.md index f9ce6db..56e1e82 100644 --- a/docs/src/intro.md +++ b/docs/src/intro.md @@ -14,7 +14,7 @@ Next line defines the problem size ```@julia m, n, t = 5, 5, 4 ``` -In this example, we have number of columns and row, `m` and `n` respectively, equal 5. Parameter `t` tells how many spins are creating a cluster. +In this example, number of columns and row, `m` and `n` respectively, is equal 5. Parameter `t` tells how many spins are creating a cluster. `SpinGlassPEPS.jl` enables to perform calculations not only on CPU, but also on GPU. If you want to switch on GPU mode, then type ```@julia @@ -63,6 +63,12 @@ params = MpsParameters(bond_dim, tol_var, max_num_sweeps, search_params = SearchParameters(num_states, δp) ``` +User can not only calculate the ground state of the given problem, but also find exitations in the system. To achieve this, the user must specify the energy range `eng` above the ground state within which the solver should search for low-energy excitations. The `SpinGlassPEPS.jl` algorithm seeks large independent excitations, meaning states that are far from each other in a Hamming sense, so states that differ from each other by at least a `hamming_dist` distance – this distance is provided by the user. +```@julia +eng = 10 +hamming_dist = 10 +``` + With this prepared set of parameters, we are ready for the actual computations. The first step is to create the Ising graph. In the Ising graph, nodes are formed by the spin positions, and interactions between them are represented by the edges. ```@julia ig = ising_graph(instance) @@ -89,7 +95,8 @@ ctr = MpsContractor{Strategy, NoUpdate}(net, [β], graduate_truncation, params; Finally the call ```@julia -sol_peps, s = low_energy_spectrum(ctr, search_params, merge_branches(ctr)) +sol_peps, schmidts = low_energy_spectrum(ctr, search_params, merge_branches(ctr, :fit, SingleLayerDroplets(eng, hamming_dist, :hamming))) + ``` which runs branch and bound algorithm included in `SpinGlassPEPS.jl` It is actual solver, which iteratively explores the state space in search of the most probable states. The probabilities of a given configuration are calculated approximately through the contractions of the tensor network. diff --git a/docs/src/sgn/api.md b/docs/src/sgn/api.md new file mode 100755 index 0000000..cf987b7 --- /dev/null +++ b/docs/src/sgn/api.md @@ -0,0 +1,66 @@ +# Library + +```@meta +CurrentModule = SpinGlassNetworks +``` + +## Ising Graphs +```@docs +inter_cluster_edges +prune +couplings +``` + +## Clustered Hamiltonian +```@docs +split_into_clusters +decode_clustered_hamiltonian_state +rank_reveal +energy +energy_2site +cluster_size +bond_energy +exact_cond_prob +truncate_clustered_hamiltonian +``` + +## Belief propagation +```@docs +local_energy +interaction_energy +get_neighbors +MergedEnergy +update_message +merge_vertices_cl_h +projector +SparseCSC +``` + +## Projectors +```@docs +PoolOfProjectors +get_projector! +add_projector! +empty! +``` + +## Spectrum +```@docs +Spectrum +matrix_to_integers +gibbs_tensor +brute_force +``` + +## Truncate +```@docs +truncate_clustered_hamiltonian_1site_BP +truncate_clustered_hamiltonian_2site_energy +select_numstate_best +``` + +## Auxiliary Functions +```@docs +zephyr_to_linear +load_openGM +``` \ No newline at end of file diff --git a/docs/src/sgn/bp.md b/docs/src/sgn/bp.md new file mode 100755 index 0000000..918f826 --- /dev/null +++ b/docs/src/sgn/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/sgn/clh.md b/docs/src/sgn/clh.md new file mode 100755 index 0000000..c3ba34a --- /dev/null +++ b/docs/src/sgn/clh.md @@ -0,0 +1,24 @@ +# 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 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 +``` + +## Simple example + +```@example +using SpinGlassNetworks + +# Prepare simple instance +instance = "$(@__DIR__)/../../src/instances/square_diagonal/5x5/diagonal.txt" +ig = ising_graph(instance) + +# Create clustered Hamiltonian +cl_h = clustered_hamiltonian( + ig, + cluster_assignment_rule = super_square_lattice((5,5,4)) +) +``` \ No newline at end of file diff --git a/docs/src/sgn/images/annealing.png b/docs/src/sgn/images/annealing.png new file mode 100755 index 0000000..6ca60bb Binary files /dev/null and b/docs/src/sgn/images/annealing.png differ diff --git a/docs/src/sgn/images/bb.png b/docs/src/sgn/images/bb.png new file mode 100755 index 0000000..32b0edd Binary files /dev/null and b/docs/src/sgn/images/bb.png differ diff --git a/docs/src/sgn/images/branch_bound.png b/docs/src/sgn/images/branch_bound.png new file mode 100755 index 0000000..c42f646 Binary files /dev/null and b/docs/src/sgn/images/branch_bound.png differ diff --git a/docs/src/sgn/images/clustering.png b/docs/src/sgn/images/clustering.png new file mode 100755 index 0000000..999f783 Binary files /dev/null and b/docs/src/sgn/images/clustering.png differ diff --git a/docs/src/sgn/images/contract.png b/docs/src/sgn/images/contract.png new file mode 100755 index 0000000..97007ea Binary files /dev/null and b/docs/src/sgn/images/contract.png differ diff --git a/docs/src/sgn/images/explain.png b/docs/src/sgn/images/explain.png new file mode 100755 index 0000000..de99697 Binary files /dev/null and b/docs/src/sgn/images/explain.png differ diff --git a/docs/src/sgn/images/graphs.png b/docs/src/sgn/images/graphs.png new file mode 100755 index 0000000..dd4f580 Binary files /dev/null and b/docs/src/sgn/images/graphs.png differ diff --git a/docs/src/sgn/images/lattice.png b/docs/src/sgn/images/lattice.png new file mode 100755 index 0000000..5ece9f0 Binary files /dev/null and b/docs/src/sgn/images/lattice.png differ diff --git a/docs/src/sgn/images/layout.png b/docs/src/sgn/images/layout.png new file mode 100755 index 0000000..e41a7b6 Binary files /dev/null and b/docs/src/sgn/images/layout.png differ diff --git a/docs/src/sgn/images/peg.png b/docs/src/sgn/images/peg.png new file mode 100755 index 0000000..986ff93 Binary files /dev/null and b/docs/src/sgn/images/peg.png differ diff --git a/docs/src/sgn/images/pegasus.png b/docs/src/sgn/images/pegasus.png new file mode 100755 index 0000000..4fff2ce Binary files /dev/null and b/docs/src/sgn/images/pegasus.png differ diff --git a/docs/src/sgn/images/peps_graph.png b/docs/src/sgn/images/peps_graph.png new file mode 100755 index 0000000..27a8dcf Binary files /dev/null and b/docs/src/sgn/images/peps_graph.png differ diff --git a/docs/src/sgn/images/prob.png b/docs/src/sgn/images/prob.png new file mode 100755 index 0000000..d2be3d7 Binary files /dev/null and b/docs/src/sgn/images/prob.png differ diff --git a/docs/src/sgn/images/sd.png b/docs/src/sgn/images/sd.png new file mode 100755 index 0000000..67c1ef8 Binary files /dev/null and b/docs/src/sgn/images/sd.png differ diff --git a/docs/src/sgn/images/square_cross_double.png b/docs/src/sgn/images/square_cross_double.png new file mode 100755 index 0000000..f142c0b Binary files /dev/null and b/docs/src/sgn/images/square_cross_double.png differ diff --git a/docs/src/sgn/images/square_cross_single.png b/docs/src/sgn/images/square_cross_single.png new file mode 100755 index 0000000..c95f142 Binary files /dev/null and b/docs/src/sgn/images/square_cross_single.png differ diff --git a/docs/src/sgn/images/square_diag.png b/docs/src/sgn/images/square_diag.png new file mode 100755 index 0000000..3669a4b Binary files /dev/null and b/docs/src/sgn/images/square_diag.png differ diff --git a/docs/src/sgn/images/square_double.png b/docs/src/sgn/images/square_double.png new file mode 100755 index 0000000..6a6d20a Binary files /dev/null and b/docs/src/sgn/images/square_double.png differ diff --git a/docs/src/sgn/images/square_single.png b/docs/src/sgn/images/square_single.png new file mode 100755 index 0000000..a9d19e8 Binary files /dev/null and b/docs/src/sgn/images/square_single.png differ diff --git a/docs/src/sgn/images/svd_truncate.png b/docs/src/sgn/images/svd_truncate.png new file mode 100755 index 0000000..da20345 Binary files /dev/null and b/docs/src/sgn/images/svd_truncate.png differ diff --git a/docs/src/sgn/images/trans.png b/docs/src/sgn/images/trans.png new file mode 100755 index 0000000..23f6a88 Binary files /dev/null and b/docs/src/sgn/images/trans.png differ diff --git a/docs/src/sgn/images/zep.png b/docs/src/sgn/images/zep.png new file mode 100755 index 0000000..962ce43 Binary files /dev/null and b/docs/src/sgn/images/zep.png differ diff --git a/docs/src/sgn/images/zephyr.png b/docs/src/sgn/images/zephyr.png new file mode 100755 index 0000000..1e60ede Binary files /dev/null and b/docs/src/sgn/images/zephyr.png differ diff --git a/docs/src/sgn/images/zipper.png b/docs/src/sgn/images/zipper.png new file mode 100755 index 0000000..3638ef4 Binary files /dev/null and b/docs/src/sgn/images/zipper.png differ diff --git a/docs/src/sgn/index.md b/docs/src/sgn/index.md new file mode 100755 index 0000000..7fd6448 --- /dev/null +++ b/docs/src/sgn/index.md @@ -0,0 +1,6 @@ +# SpinGlassNetworks + +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. + + + diff --git a/docs/src/sgn/ising.md b/docs/src/sgn/ising.md new file mode 100755 index 0000000..f2bec58 --- /dev/null +++ b/docs/src/sgn/ising.md @@ -0,0 +1,25 @@ +# Ising model + +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. + +In `SpinGlassPEPS.jl` package, an Ising graph can be created using the command `ising_graph`. +```@docs +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 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 +# Create Ising instance +instance = "$(@__DIR__)/../../src/instances/square_diagonal/5x5/diagonal.txt" +ig = ising_graph(instance) + +# View graph properties +@show biases(ig), couplings(ig) +``` \ No newline at end of file diff --git a/docs/src/sgn/lattice.md b/docs/src/sgn/lattice.md new file mode 100755 index 0000000..05f4821 --- /dev/null +++ b/docs/src/sgn/lattice.md @@ -0,0 +1,105 @@ +# 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 an exploration of spin interactions beyond the traditional square lattice framework. +```@raw html + +``` + +In `SpinGlassPEPS.jl` solver, a grid of this type can be loaded using the command `super_square_lattice`. + +```@docs +super_square_lattice +``` + +Below you find simple example of usage `super_square_latttice` function. + +```@example +using SpinGlassEngine, SpinGlassNetworks, LabelledGraphs + +instance = "$(@__DIR__)/../../src/instances/square_diagonal/5x5/diagonal.txt" +ig = ising_graph(instance) + +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 + +``` + +In `SpinGlassPEPS.jl` solver, a grid of this type can be loaded using the command `pegasus_lattice`. + +```@docs +pegasus_lattice +``` + +Below you find simple example of usage `pegasus_latttice` function. + +```@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))/2) +``` + + +## 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 + +``` + +In `SpinGlassPEPS.jl` solver, a grid of this type can be loaded using the command `zephyr_lattice`. + +```@docs +zephyr_lattice +``` + +Below you find simple example of usage `zephyr_latttice` function. + +```@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))) +``` \ No newline at end of file diff --git a/docs/src/sgn/userguide.md b/docs/src/sgn/userguide.md new file mode 100755 index 0000000..cb92310 --- /dev/null +++ b/docs/src/sgn/userguide.md @@ -0,0 +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. + +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.