extend contractor interface (#32)

* extend contractor interface

* add automate onGPU

* new docs

* add bench from publication

* version changed

* docs remove API

* rm example from paper

---------

Co-authored-by: annamariadziubyna <[email protected]>

Project.toml

@@ -1,7 +1,7 @@
 name = "SpinGlassEngine"
 uuid = "0563570f-ea1b-4080-8a64-041ac6565a4e"
 authors = ["Anna Maria Dziubyna <[email protected]>", "Tomasz Śmierzchalski <[email protected]>", "Bartłomiej Gardas <[email protected]>", "Konrad Jałowiecki <[email protected]>", "Łukasz Pawela <[email protected]>", "Marek M. Rams <[email protected]>"]
-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"

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 =

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
 <img src="../images/zipper_final.png" width="200%" class="center"/>
 ```
@@ -25,14 +25,15 @@ With the `SVDTruncate` method, the Matrix Product State (MPS) is systematically
 <img src="../images/svd_truncate.png" width="50%" class="center"/>
 ```
 
-# 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
 <img src="../images/square_single.png" width="50%" class="center"/>
@@ -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
 <img src="../images/trans.png" width="200%" class="center"/>
 ```

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)
 ```

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
 ```

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}

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

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

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.
 

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 = []