Docs

docs/src/api.md

@@ -54,7 +54,6 @@ Flip
 Droplet
 NoDroplets
 hamming_distance
-unpack_droplets
 perm_droplet
 filter_droplets
 my_push!

docs/src/params.md

@@ -1,6 +1,5 @@
 # Contracting PEPS tensor network
-Once we construct the tensor network, we can proceed with its contraction. The first step involves preparing structures to store information about the approximate contraction using the MPS-MPO method and the exploration of states through the branch-and-bound algorithm.
-
+With the tensor network constructed, we now prepare to initiate the core branch-and-bound algorithm. The process begins with preparing data structures that store information about approximate contraction using the boundary MPS-MPO method and the exploration of states through the branch-and-bound algorithm. 
 ```@docs
 MpsContractor
 ```
@@ -11,12 +10,12 @@ MpsParameters
 SearchParameters
 ```
 
-# Strategy 
+# Optimizing boundary MPS 
 In the boundary MPS-MPO approach we apply Matrix Product Operator (MPO) to appropriate sites of Matrix Product State (MPS). In this context, the absorption of a MPO into a MPS leads to an exponential growth of the bond dimension. Hence, a truncation scheme is necessary to mitigate this issue and to keep the bond dimension in a reasonable size. 
-Our package offers users the flexibility to choose between three distinct methods for optimizing the boundary MPS used in contracting the tensor network: 
+Our package offers users the flexibility to choose between two distinct methods for optimizing the boundary MPS used in contracting the tensor network: 
 * `Zipper`
 * `SVDTruncate`.
-`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)
+`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). Details are described in [Ref.](https://arxiv.org/abs/2411.16431)
 ```@raw html
 <img src="../images/zipper_final.png" width="200%" class="center"/>
 ```
@@ -25,12 +24,12 @@ With the `SVDTruncate` method, the Matrix Product State (MPS) is systematically
 <img src="../images/svd_truncate.png" width="50%" class="center"/>
 ```
 
-# Sparsity  
+# Sparsity of tensors
 The `Sparsity` parameter controls whether 
 * `Dense` 
 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.
+tensor representations are used during calculations. `Sparse` tensors are particularly useful for handling large clusters of 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. Detailed infomation about employing sparsity of tensors can be found in [Ref.](https://arxiv.org/abs/2411.16431)
 
 # Geometry
 One can specify the type of the node used within the tensor networks: 
@@ -66,7 +65,7 @@ KingSingleNode
 SquareCrossDoubleNode
 ```
 
-# Layout 
+# Decomposition of PEPS into MPOs 
 `SpinGlassPEPS.jl` allows for different decompositions of the PEPS network into MPOs:
 * `GaugesEnergy`
 * `EnergyGauges`

docs/src/search.md

@@ -1,14 +1,17 @@
 # Branch and bound search
-Here you find the main function of the package, which is an actual solver.
+Here you find the main function of the package, which is an actual branch and bound solver.
 
 ```@docs
 low_energy_spectrum
 merge_branches
 merge_branches_blur
 ```
-Results of the branch and bound search are stored in a Solution structure.
+
+# Output structure
+Results of the branch and bound search are stored in a `Solution` structure. To decode Potts Hamiltonian states into binary Ising states one can use `decode_potts_hamiltonian_state` function.
 ```@docs
 Solution
+SpinGlassNetworks.decode_potts_hamiltonian_state
 ```
 
 # Droplet search
@@ -22,4 +25,5 @@ This behavior is controlled by two key parameters:
 By adjusting these parameters, users can search for different excitations while ensuring that only sufficiently distinct ones are included.
 ```@docs
 SingleLayerDroplets
-```
+unpack_droplets
+```

src/PEPS.jl

@@ -35,14 +35,14 @@ Construct a Projected Entangled Pair States (PEPS) network.
 # Arguments
 - `m::Int`: Number of rows in the PEPS lattice.
 - `n::Int`: Number of columns in the PEPS lattice.
-- `potts_hamiltonian::LabelledGraph`: Potts Hamiltonian representing the Hamiltonian.
+- `potts_hamiltonian::LabelledGraph`: Potts Hamiltonian.
 - `transformation::LatticeTransformation`: Transformation of the PEPS lattice, as it can be rotated or reflected. 
-- `gauge_type::Symbol=:id`: Type of gauge to initialize (default is identity).
+- `gauge_type::Symbol=:id`: Type of gauge initialization: :id or :rand (default is :id).
 
 # Type Parameters
 - `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).
+- `R <: Real`: The numeric precision type for real values (e.g., Float64 or Float32).
 
 # Returns
 An instance of PEPSNetwork{T, S, R}.

src/droplets.jl

@@ -460,16 +460,23 @@ end
 """
 $(TYPEDSIGNATURES)
 
-Unpack droplets in a solution structure to create a new solution with individual excitations.
+Unpack droplets in a solution structure to reconstruct low energy spectrum from identified localized excitations.
+
+This function processes a solution structure containing ground state and excitations on the top of it 
+and unpacks them into individual excitations building low energy spectrum. 
+Each droplet is converted into a separate entry in the new solution. 
+Probabilities of the unpacked states are adjusted based on the inverse temperature parameter.
 
 ## Arguments
-- `sol`: The input solution containing droplets to be unpacked.
-- `β::Real`: The inverse temperature parameter used for probability adjustments.
+- `sol::Solution`: The input solution structure
+- `β::Real`: The inverse temperature parameter used to adjust probabilities when unpacking droplets.
 
 ## Returns
-- `new_sol`: A new solution where droplets are unpacked into individual excitations.
+- `new_sol::Solution`: A new solution where:
+  - Each droplet encoded as excitation on the top of a ground state is unpacked into an individual low energy state.
+  - Energies, states, and probabilities are adjusted to reflect the unpacked structure.
 """
-function unpack_droplets(sol, β)  # have β in sol ?
+function unpack_droplets(sol, β)
     energies = typeof(sol.energies[begin])[]
     states = typeof(sol.states[begin])[]
     probs = typeof(sol.probabilities[begin])[]

src/search.jl

@@ -44,13 +44,12 @@ A struct representing a solution obtained from a low-energy spectrum search.
 - `states::Vector{Vector{Int}}`: A vector of state configurations corresponding to the energies.
 - `probabilities::Vector{<:Real}`: The probabilities associated with each discovered state.
 - `degeneracy::Vector{Int}`: The degeneracy of each energy level.
-- `largest_discarded_probability::Real`: The largest probability of the largest discarded state.
+- `largest_discarded_probability::Real`: The probability of the largest discarded state.
 - `droplets::Vector{Droplets}`: A vector of droplets associated with each state.
 - `spins::Vector{Vector{Int}}`: The spin configurations corresponding to each state.
 
-The `Solution` struct holds information about the results of a low-energy spectrum search, including the energy levels,
-state configurations, probabilities, degeneracy, and additional details such as droplets and spin configurations.
-Users can access this information to analyze and interpret the search results.
+The `Solution` struct holds information about the results of a low-energy spectrum search, including the energies,
+state configurations, probabilities, degeneracy, and additional details such as droplets enabling to reconstruct the low energy spectrum from the ground state.
 """
 struct Solution
     energies::Vector{<:Real}