diff --git a/Project.toml b/Project.toml index cb913c83..3bea72f1 100644 --- a/Project.toml +++ b/Project.toml @@ -1,7 +1,7 @@ name = "SpinGlassEngine" uuid = "0563570f-ea1b-4080-8a64-041ac6565a4e" authors = ["Anna Maria Dziubyna ", "Tomasz Śmierzchalski ", "Bartłomiej Gardas ", "Konrad Jałowiecki ", "Łukasz Pawela ", "Marek M. Rams "] -version = "1.4.0" +version = "1.5.0" [deps] CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba" @@ -32,7 +32,7 @@ MKL = "0.4.3" NNlib = "0.9.14" ProgressMeter = "1.10" SpinGlassExhaustive = "1.0.0" -SpinGlassNetworks = "1.2.0" +SpinGlassNetworks = "1.3.0" SpinGlassTensors = "1.1.3" Statistics = "1.7.0" TensorCast = "0.4" diff --git a/docs/make.jl b/docs/make.jl index 147c2d97..137366fa 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -5,8 +5,9 @@ _pages = [ "Tensor network" => "peps.md", "Search parameters" => "params.md", "Low energy spectrum" => "search.md", - "API Reference for auxiliary functions" => "api.md", ] + # "API Reference for auxiliary functions" => "api.md", +# ] # ============================ format = diff --git a/docs/src/params.md b/docs/src/params.md index 5b9adc8b..6ab575bb 100644 --- a/docs/src/params.md +++ b/docs/src/params.md @@ -16,7 +16,7 @@ In the boundary MPS-MPO approach we apply Matrix Product Operator (MPO) to appro Our package offers users the flexibility to choose between three distinct methods for optimizing the boundary MPS used in contracting the tensor network: * `Zipper` * `SVDTruncate`. -`Zipper` method combines randomized truncated Singular Value Decomposition (SVD) and a variational scheme. +`Zipper` method combines a zipper scheme of [Ref.](https://arxiv.org/abs/2310.08533). with the standard variational optimization of the resulting MPS [(see Ref.)](https://arxiv.org/abs/0907.2796) ```@raw html ``` @@ -25,14 +25,15 @@ With the `SVDTruncate` method, the Matrix Product State (MPS) is systematically ``` -# Sparsity -Our software package acknowledges the importance of two fundamental methodologies in tensor processing +# Sparsity +The `Sparsity` parameter controls whether * `Dense` -* `Sparse`. -The latter, referred to as sparsity, plays a pivotal role in manipulation on large tensors. To accommodate this, our package offers the flexibility to choose the `Sparse` mode. In this mode, tensors are not explicitly constructed but are stored in structures and represented as blocks, in which not every dimension is contracted. This choice not only optimizes memory utilization but also significantly improves computational efficiency. In the `Dense` mode tensors are build explicitly. +or +* `Sparse` +tensor representations are used during calculations. `Sparse` tensors are particularly useful for handling large clusters containing around 10 to 20 spins. When bond dimensions increase, constructing PEPS tensors explicitly (triggered by `Sparsity=Dense`) becomes computationally expensive and quickly infeasible. In contrast, setting `Sparsity=Sparse` avoids the direct construction of full tensors. Instead, it performs optimal contractions on smaller tensor structures, which are then combined to contract the entire network efficiently. This approach leverages the internal structure of the individual tensors to reduce computational overhead and memory usage. # Geometry - +One can specify the type of the node used within the tensor networks: * `SquareSingleNode` ```@raw html @@ -66,7 +67,7 @@ SquareCrossDoubleNode ``` # Layout -`SpinGlassPEPS.jl` allows for different decompositions of the network into MPOs: +`SpinGlassPEPS.jl` allows for different decompositions of the PEPS network into MPOs: * `GaugesEnergy` * `EnergyGauges` * `EngGaugesEng` @@ -77,7 +78,12 @@ For complex problems, the solution may depend on the choice of decomposition. ``` # Lattice transformations -Our package offers users the ability to undergo diverse transformations of PEPS network. Notably, users can apply `rotations`, occurring in multiples of $\frac{\pi}{2}$ radians, and `reflections` along various axes. These transformations include rotations and reflections around the horizontal (x), vertical (y), diagonal, and antidiagonal axes. Transformations are used to contract PEPS and perform search starting from different sites of the lattice. +Our package provides users with the ability to apply various transformations to the PEPS network, allowing for flexibility in tensor network manipulation. The available transformations include `rotations` by multiples of $\frac{\pi}{2}$ radians and `reflections` along different axes. Specifically, users can apply rotations and reflections around the horizontal (x), vertical (y), diagonal, and antidiagonal axes. + +These transformations are useful when contracting PEPS or performing searches from different lattice sites. For instance, the `transform` parameter allows the user to rotate the quasi-2D graph, which influences the order of sweeping through local variables during branch-and-bound search. By rotating the tensor network, the search and contraction process can start from different positions on the 2D grid, improving the stability and robustness of the results. + +In practice, searches can be performed across all eight possible transformations (four rotations and four reflections, `all_lattice_transformations`) of the 2D grid, comparing the energies obtained for each configuration to identify the most optimal outcome. + ```@raw html ``` diff --git a/docs/src/peps.md b/docs/src/peps.md index aa39442b..bbf6c147 100644 --- a/docs/src/peps.md +++ b/docs/src/peps.md @@ -20,6 +20,7 @@ Strategy = Zipper transform = rotation(0) Layout = GaugesEnergy Sparsity = Sparse +R = Float64 ig = ising_graph(instance) potts_h = potts_hamiltonian( @@ -28,5 +29,5 @@ potts_h = potts_hamiltonian( cluster_assignment_rule=super_square_lattice((m, n, t)) ) -net = PEPSNetwork{KingSingleNode{Layout}, Sparsity}(m, n, potts_h, transform) +net = PEPSNetwork{KingSingleNode{Layout}, Sparsity, R}(m, n, potts_h, transform) ``` diff --git a/docs/src/search.md b/docs/src/search.md index 8392d9d0..e7a14e4b 100644 --- a/docs/src/search.md +++ b/docs/src/search.md @@ -12,7 +12,14 @@ Solution ``` # Droplet search -`SpinGlassPEPS.jl` offers the possibility not only finding low lying energy states, but also droplet excitations. In order to search for droplets, one need to choose the option `SingleLayerDroplets` in `merge_branches`. +`SpinGlassPEPS.jl` provides the capability to find not only low-energy states but also droplet excitations. To search for droplets, the `SingleLayerDroplets` option must be selected in the `merge_branches` function. + +Droplets are identified during the optional `merge_branches` step, which can be invoked within the `low_energy_spectrum` function that runs the branch-and-bound algorithm. This search focuses on finding diverse excitations within a specific energy range above the ground state. An excitation is accepted only if its Hamming distance from any previously identified excitation exceeds a predefined threshold. + +This behavior is controlled by two key parameters: +* `energy_cutoff`: Defines the maximum allowed energy above the ground state for considering an excitation. +* `hamming_cutoff`: Sets the minimum Hamming distance required between excitations for them to be classified as distinct. +By adjusting these parameters, users can search for different excitations while ensuring that only sufficiently distinct ones are included. ```@docs SingleLayerDroplets ``` \ No newline at end of file diff --git a/src/PEPS.jl b/src/PEPS.jl index a4f6dcc4..b59f09ff 100644 --- a/src/PEPS.jl +++ b/src/PEPS.jl @@ -40,11 +40,12 @@ Construct a Projected Entangled Pair States (PEPS) network. - `gauge_type::Symbol=:id`: Type of gauge to initialize (default is identity). # Type Parameters -- `T <: AbstractGeometry`: Type of geometry for the PEPS lattice. It can be `SquareSingleNode`, `SquareDoubleNode`, `KingSingleNode`, `SquareCrossDoubleNode`. +- `T <: AbstractGeometry`: Type of node used within the PEPS tensor network. It can be `SquareSingleNode`, `SquareDoubleNode`, `KingSingleNode`, `SquareCrossDoubleNode`. - `S <: AbstractSparsity`: Type of sparsity for the PEPS tensors: `Dense` or `Sparse`. +- `R <: Real``: The numeric precision type for real values (e.g., Float64). # Returns -An instance of PEPSNetwork{T, S}. +An instance of PEPSNetwork{T, S, R}. """ mutable struct PEPSNetwork{T<:AbstractGeometry,S<:AbstractSparsity,R<:Real} <: AbstractGibbsNetwork{Node,PEPSNode,R} diff --git a/src/contractor.jl b/src/contractor.jl index 65329d84..7c6591d2 100644 --- a/src/contractor.jl +++ b/src/contractor.jl @@ -71,8 +71,19 @@ A struct representing control parameters for the MPO-MPS (Matrix Product Operato - `iters_var::Int`: The number of iterations for variational optimization. Default is 1. - `Dtemp_multiplier::Int`: A multiplier for the bond dimension when temporary bond dimensions are computed. Default is 2. - `method::Symbol`: The type of SVD method to use (e.g., `:psvd_sparse`). Default is `:psvd_sparse`. - -The `MpsParameters` struct encapsulates various control parameters that influence the behavior and accuracy of the MPO-MPS contraction scheme used for PEPS network calculations. + +Keyword Arguments: +- `bond_dim`: Specifies the maximum bond dimension (default is typemax(Int)). +- `var_tol`: Tolerance for the variational solver (default is 1E-8). +- `num_sweeps`: Maximum number of sweeps for variational compression (default is 4). +- `tol_SVD`: Tolerance for SVD operations (default is 1E-16). +- `iters_svd`: Number of SVD iterations (default is 1). +- `iters_var`: Number of iterations for variational optimization (default is 1). +- `Dtemp_multiplier`: Multiplier for temporary bond dimensions (default is 2). +- `method`: SVD method to use, such as :psvd_sparse (default is :psvd_sparse). + +Description: +The MpsParameters struct encapsulates various control parameters that influence the behavior and accuracy of the MPO-MPS contraction scheme used in PEPS network calculations. This allows fine-tuning of tolerances, iteration limits, and methods for efficient and accurate tensor network contractions. """ struct MpsParameters{S<:Real} bond_dimension::Int @@ -126,23 +137,28 @@ sparsity(net::PEPSNetwork{T,S}) where {T,S} = S """ $(TYPEDSIGNATURES) -A mutable struct representing a contractor for contracting a PEPS (Projected Entangled Pair States) network using the MPO-MPS (Matrix Product Operator - Matrix Product State) scheme. - -# Fields -- `peps::PEPSNetwork{T, S}`: The PEPS network to be contracted. -- `betas::Vector{<:Real}`: A vector of inverse temperatures (β) used during the search. The last one is the target one. This parameter plays a crucial role: a larger β enables a finer focus on low-energy states, although it may compromise the numerical stability of tensor network contraction. Determining the optimal β could be instance-dependent, and experimental exploration might be necessary for different classes of instances. -- `graduate_truncation::Bool`: The truncation method to use for gradually truncating MPS bond dimensions. -- `params::MpsParameters`: Control parameters for the MPO-MPS contraction. -# Optional Arguments -- `onGPU::Bool`: A flag indicating whether the contraction is performed on a GPU. Default is `true`. -- `depth`: An integer specifying the iteration depth for variational sweeps in Zipper algorithm. Default is `0` which means variational sweep is done on all lattice sites. - -The `MpsContractor` function defines the contractor structure responsible for contracting a PEPS network using the MPO-MPS scheme. -It encapsulates various components and settings required for the contraction process. +MpsContractor is a mutable struct that represents the contractor responsible for contracting a PEPS (Projected Entangled Pair States) network using the MPO-MPS (Matrix Product Operator - Matrix Product State) scheme. + +# Type Parameters +- `T<:AbstractStrategy`: Specifies the contraction strategy to be employed. +- `R<:AbstractGauge`: Specifies the gauge-fixing method used for optimizing the contraction. +- `S<:Real`: Represents the numeric precision type for real values (e.g., Float64). + +# Constructor +This constructor initializes an instance of MpsContractor with the following arguments: +Positional arguments: +- `net`: The PEPS network to be contracted. +- `params`: Contains the control parameters for the MPO-MPS contraction, such as bond dimension and the number of sweeps. +Keyword arguments: +- `beta::S`: The inverse temperature, β, which is crucial for focusing on low-energy states. A larger β sharpens the focus on these states but may reduce the numerical stability of the tensor contraction. The optimal value of β often depends on the problem instance. +- `graduate_truncation::Bool`: A flag indicating whether bond dimensions in the MPS are truncated progressively. When set to true, this truncation method adjusts the bond dimensions gradually during contraction. +- `onGPU::Bool`: A flag indicating whether the computation should be performed on a GPU (default is true). +- `depth::Int`: Specifies the depth of variational sweeps during the Zipper algorithm. A value of 0 implies a full variational sweep across all lattice sites. +The constructor sets up the internal structure of the contractor, including the MPO layers, search order for nodes, and storage for contraction statistics. """ mutable struct MpsContractor{T<:AbstractStrategy,R<:AbstractGauge,S<:Real} <: - AbstractContractor + AbstractContractor peps::PEPSNetwork{T} where {T} beta::S graduate_truncation::Bool @@ -186,6 +202,45 @@ mutable struct MpsContractor{T<:AbstractStrategy,R<:AbstractGauge,S<:Real} <: end end +function MpsContractor( + ::Type{T}, + ::Type{R}, + ::Type{S}, + net, + params; + beta::S, + graduate_truncation::Bool, + onGPU = true, + depth::Int = 0, +) where {T, R, S} + return MpsContractor{T,R,S}(net, params; beta, graduate_truncation, onGPU, depth) +end + +function MpsContractor( + ::Type{T}, + ::Type{R}, + net, + params; + beta::S, + graduate_truncation::Bool, + onGPU = true, + depth::Int = 0, +) where {T, R, S} + return MpsContractor(T, R, S, net, params; beta, graduate_truncation, onGPU, depth) +end + +function MpsContractor( + ::Type{T}, + net, + params; + beta::S, + graduate_truncation::Bool, + onGPU = true, + depth::Int = 0, +) where {T, S} + return MpsContractor(T, NoUpdate, net, params; beta, graduate_truncation, onGPU, depth) +end + """ $(TYPEDSIGNATURES) Get the strategy used to contract the PEPS network. @@ -285,10 +340,7 @@ Construct and memoize the (bottom) Matrix Product State (MPS) using Singular Val This function constructs the (bottom) MPS using SVD for a given row in the PEPS network contraction. It recursively builds the MPS row by row, performing canonicalization, truncation, and compression steps as needed based on the specified parameters in `ctr.params`. The resulting MPS is memoized for efficient reuse. """ -@memoize Dict function mps( - ctr::MpsContractor{SVDTruncate,R,S}, - i::Int, -) where {R,S} +@memoize Dict function mps(ctr::MpsContractor{SVDTruncate,R,S}, i::Int) where {R,S} Dcut = ctr.params.bond_dimension tolV = ctr.params.variational_tol tolS = ctr.params.tol_SVD @@ -328,10 +380,7 @@ Construct and memoize the (bottom) Matrix Product State (MPS) approximation usin This function constructs the (bottom) MPS approximation using SVD for a given row in the PEPS network contraction. It recursively builds the MPS row by row, performing canonicalization, and truncation steps based on the specified parameters in `ctr.params`. The resulting MPS approximation is memoized for efficient reuse. """ -@memoize Dict function mps_approx( - ctr::MpsContractor{SVDTruncate,R,S}, - i::Int, -) where {R,S} +@memoize Dict function mps_approx(ctr::MpsContractor{SVDTruncate,R,S}, i::Int) where {R,S} if i > ctr.peps.nrows W = mpo(ctr, ctr.layers.main, ctr.peps.nrows) return IdentityQMps(S, local_dims(W, :down); onGPU = ctr.onGPU) # F64 for now @@ -370,10 +419,7 @@ Construct and memoize the top Matrix Product State (MPS) using the Zipper (trunc This function constructs the top Matrix Product State (MPS) using the Zipper (truncated Singular Value Decomposition) method for a given row in the PEPS network contraction. It recursively builds the MPS row by row, performing canonicalization, and truncation steps based on the specified parameters in `ctr.params`. The resulting MPS is memoized for efficient reuse. """ -@memoize Dict function mps_top( - ctr::MpsContractor{Zipper,R,S}, - i::Int, -) where {R,S} +@memoize Dict function mps_top(ctr::MpsContractor{Zipper,R,S}, i::Int) where {R,S} Dcut = ctr.params.bond_dimension tolV = ctr.params.variational_tol tolS = ctr.params.tol_SVD @@ -711,22 +757,14 @@ function sweep_gauges!( end -function update_gauges!( - ctr::MpsContractor{T,S}, - row::Site, - ::Val{:down}, -) where {T,S} +function update_gauges!(ctr::MpsContractor{T,S}, row::Site, ::Val{:down}) where {T,S} for i ∈ 1:row-1 sweep_gauges!(ctr, i) end end -function update_gauges!( - ctr::MpsContractor{T,S}, - row::Site, - ::Val{:up}, -) where {T,S} +function update_gauges!(ctr::MpsContractor{T,S}, row::Site, ::Val{:up}) where {T,S} for i ∈ row-1:-1:1 sweep_gauges!(ctr, i) end diff --git a/src/droplets.jl b/src/droplets.jl index 18d05424..a5717b2f 100644 --- a/src/droplets.jl +++ b/src/droplets.jl @@ -21,14 +21,14 @@ Base.copy(s::NoDroplets) = s Base.getindex(s::NoDroplets, ::Any) = NoDroplets() """ -A data structure representing the properties and criteria for single-layer droplets in the context of the SpinGlassPEPS package. +A data structure representing the properties and criteria for identifying single-layer droplets in the context of the SpinGlassPEPS package. -A `SingleLayerDroplets` object is used to specify the maximum energy, minimum size, and metric for single-layer droplets in the SpinGlassPEPS system. +A `SingleLayerDroplets` object is used to specify the maximum energy, minimum size, and metric for single-layer droplets in the SpinGlassPEPS. ## Fields -- `max_energy::Real`: The maximum allowed excitation energy for single-layer droplets. It is typically a real number. -- `min_size::Int`: The minimum size (Hamming cutoff) required for a single-layer droplet to be considered significant. -- `metric::Symbol`: The metric used to evaluate the significance of a single-layer droplet. Default is `:no_metric`. `:hamming` treats Hamming distances as matric. +- `max_energy::Real`: The maximum allowed excitation energy above the ground state. It is typically a real number. +- `min_size::Int`: The minimum Hamming distance required between excitations for them to be considered distinct. +- `metric::Symbol`: The metric used to evaluate the significance of a single-layer droplet. Default is `:no_metric`. `:hamming` treats Hamming distances as a metric. - `mode::Symbol`: `:Ising` assumes Ising-type representation of the problem. `:RMF` assumes a Random Markov Field type model. Default is `:Ising`. ## Constructors diff --git a/src/search.jl b/src/search.jl index 266c2444..35dcc6b5 100644 --- a/src/search.jl +++ b/src/search.jl @@ -19,7 +19,8 @@ export SearchParameters, $(TYPEDSIGNATURES) A struct representing search parameters for low-energy spectrum search. -## Fields +## Constructor +Keyword arguments: - `max_states::Int`: The maximum number of states to be considered during the search. Default is 1, indicating a single state search. - `cutoff_prob::Real`: The cutoff probability for terminating the search. Default is 0.0, meaning no cutoff based on probability. diff --git a/test/runtests.jl b/test/runtests.jl index 24679370..3201c78b 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -8,10 +8,13 @@ using LinearAlgebra using TensorCast using Statistics using MetaGraphs +using CUDA disable_logging(LogLevel(1)) -onGPU = true +user_onGPU = true # or false, based on user's preference +gpu_available = CUDA.functional() +onGPU = user_onGPU && gpu_available using Test my_tests = []