add the docs

euro-hpc-pl · Nov 17, 2023 · 40d2a64 · 40d2a64
1 parent cb4dde3
commit 40d2a64
Show file tree

Hide file tree

Showing 15 changed files with 199 additions and 252 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -2,8 +2,11 @@ using Documenter, SpinGlassEngine
 
 _pages = [
     "Introduction" => "index.md",
-    "User Guide" => "guide.md",    
-    "API Reference" => "api.md"
+    "User Guide" => "guide.md", 
+    "Tensor network"  => "peps.md",
+    "Search parameters" => "params.md",
+    "Low energy spectrum" => "search.md",
+    "API Reference for auxiliary functions" => "api.md"
 ]
 # ============================
 

diff --git a/docs/src/api.md b/docs/src/api.md
@@ -4,14 +4,11 @@
 
 ## Search
 ```@docs
-SearchParameters
 Solution
 empty_solution
-low_energy_spectrum
 gibbs_sampling
 bound_solution
 no_merge
-merge_branches
 branch_energy
 ```
 
@@ -21,10 +18,7 @@ error_measure
 conditional_probability
 update_energy
 boundary
-local_state_for_node
 boundary_indices
-sweep_gauges!
-update_gauges!
 Gauges
 GaugeInfo
 PEPSNode
@@ -34,9 +28,6 @@ SuperPEPSNode
 ## Contractor
 ```@docs
 MpoLayers
-MpsParameters
-MpsContractor
-PEPSNetwork
 layout
 sparsity
 strategy
@@ -53,10 +44,6 @@ clear_memoize_cache_after_row
 
 ## Operations
 ```@docs
-LatticeTransformation
-rotation
-reflection
-all_lattice_transformations
 vertex_map
 check_bounds
 ```
@@ -76,4 +63,43 @@ diversity_metric
 merge_droplets
 flip_state
 
+```
+
+## PEPS
+```@docs
+SpinGlassEngine.local_energy
+SpinGlassEngine.interaction_energy
+normalize_probability
+initialize_gauges!
+decode_state
+SpinGlassEngine.bond_energy
+SpinGlassEngine.projector
+spectrum
+is_compatible
+ones_like
+tensor_map
+size
+exact_spectrum
+discard_probabilities!
+mod_wo_zero
+exact_marginal_probability
+_normalize
+projectors_site_tensor
+branch_probability
+exact_conditional_probability
+branch_solution
+gauges_list
+SquareCrossDoubleNode
+SquareSingleNode
+branch_energies
+_equalize
+nodes_search_order_Mps
+sampling
+VirtualDoubleNode
+merge_branches_blur
+fuse_projectors
+local_spins
+tensor
+branch_states
+precompute_conditional
 ```
diff --git a/docs/src/params.md b/docs/src/params.md
@@ -0,0 +1,45 @@
+# Structures to store parameters
+```@docs
+MpsParameters
+SearchParameters
+```
+
+# Strategy 
+Our package offers users the flexibility to choose between three distinct methods for contracting the tensor network: 
+* `Zipper`
+* `MPSAnnealing`
+* `SVDTruncate`.
+
+With the `SVDTruncate` method, the Matrix Product State (MPS) is systematically constructed row by row, contracting with the Matrix Product Operator (MPO) from the preceding row. The resulting MPS undergoes a Singular Value Decomposition (SVD) to trim its bond dimension, followed by variational compression. 
+On the other hand, the `MPSAnnealing` method tailors the construction of MPS based on temperature considerations, with a subsequent variational compression step. 
+
+These approaches provide users with distinct strategies to efficiently contract the tensor network, catering to different preferences and requirements in the exploration of spin systems within the SpinGlassPEPS package.
+
+# Sparsity 
+In the domain of matrix operations, our package recognizes the significance of two primary approaches: 
+* `dense` 
+* `sparse`. 
+The latter, referred to as sparsity, plays a pivotal role in various computational contexts. Frequently, the matrices involved in our calculations exhibit sparse characteristics, wherein a significant portion of their elements is zero. To accommodate this, our package offers the flexibility to choose the `sparse` mode. This option not only optimizes memory usage but also substantially enhances computational efficiency, particularly when dealing with matrices characterized by a scarcity of non-zero entries. By selecting the sparse mode, users can leverage the inherent structure of these matrices, streamlining computations, and expediting solutions for intricate problems. This feature underscores our commitment to providing users with the tools to tailor their computational strategies based on the nature of the matrices involved, ensuring optimal performance across diverse scenarios.
+
+# Layout 
+Different decompositions of the network into MPS:
+* `GaugesEnergy`
+* `EnergyGauges`
+* `EngGaugesEng`
+
+```@raw html
+<img src="../images/layout.pdf" width="200%" class="center"/>
+```
+
+# Lattice transformations
+The PEPS tensor network within our package stands out for its remarkable versatility, offering users the ability to undergo diverse transformations to meet distinct computational requirements. 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. This comprehensive set of transformations empowers researchers to meticulously adjust the orientation and arrangement of the tensor network, providing the means to optimize it for specific problem-solving strategies or align it with the geometrical considerations of their chosen application domain.
+
+```@docs
+all_lattice_transformations
+LatticeTransformation
+rotation
+reflection
+```
+
+# Gauge 
+* NoUpdate
diff --git a/docs/src/peps.md b/docs/src/peps.md
@@ -0,0 +1,18 @@
+# Constructing tensor network
+
+
+```@raw html
+<img src="../images/peps.pdf" width="200%" class="center"/>
+```
+
+```@docs
+PEPSNetwork
+```
+
+```@raw html
+<img src="../images/contract.pdf" width="200%" class="center"/>
+```
+
+```@docs
+MpsContractor
+```
diff --git a/docs/src/search.md b/docs/src/search.md
@@ -0,0 +1,11 @@
+# Branch and bound search
+
+
+```@raw html
+<img src="../images/branch_bound.pdf" width="200%" class="center"/>
+```
+
+```@docs
+low_energy_spectrum
+merge_branches
+```
diff --git a/src/PEPS.jl b/src/PEPS.jl
@@ -4,7 +4,6 @@ using LabelledGraphs
 
 export
        AbstractGibbsNetwork,
-       local_energy,
        interaction_energy,
        connecting_tensor,
        normalize_probability,
@@ -15,11 +14,15 @@ export
        mod_wo_zero,
        bond_energy,
        outer_projector,
-       bond_energy,
        projector,
        spectrum,
-       interaction_energy,
-       is_compatible
+       is_compatible,
+       ones_like,
+       _equalize,
+       _normalize,
+       branch_solution,
+       local_spins,
+       local_energy
 
 # T: type of the vertex of network
 # S: type of the vertex of underlying factor graph

diff --git a/src/contractor.jl b/src/contractor.jl
@@ -696,9 +696,7 @@ function clear_memoize_cache(ctr::MpsContractor{T, S}, row::Site, indβ::Int) wh
     end
 end
 
-"""
-$(TYPEDSIGNATURES)
-"""
+
 function sweep_gauges!(
     ctr::MpsContractor{T, GaugeStrategy},
     row::Site,
@@ -733,9 +731,7 @@ function sweep_gauges!(
     clear_memoize_cache(ctr, row, indβ)
 end
 
-"""
-$(TYPEDSIGNATURES)
-"""
+
 function sweep_gauges!(
     ctr::MpsContractor{T, GaugeStrategyWithBalancing},
     row::Site,
@@ -757,9 +753,7 @@ function sweep_gauges!(
     ψ_top * ψ_bot
 end
 
-"""
-$(TYPEDSIGNATURES)
-"""
+
 function sweep_gauges!(
     ctr::MpsContractor{T, NoUpdate},
     row::Site,
@@ -770,9 +764,7 @@ function sweep_gauges!(
 
 end
 
-"""
-$(TYPEDSIGNATURES)
-"""
+
 function update_gauges!(
     ctr::MpsContractor{T, S},
     row::Site,
@@ -784,9 +776,7 @@ function update_gauges!(
     end
 end
 
-"""
-$(TYPEDSIGNATURES)
-"""
+
 function update_gauges!(
     ctr::MpsContractor{T, S},
     row::Site,
@@ -809,26 +799,20 @@ function boundary_states(
     [res[r, :] for r ∈ 1:size(res, 1)]
 end
 
-"""
-$(TYPEDSIGNATURES)
-"""
+
 function boundary(ctr::MpsContractor{T}, node::Node) where T
     boundary(layout(ctr.peps), ctr, node)
 end
 
-"""
-$(TYPEDSIGNATURES)
-"""
+
 function local_state_for_node(
     ctr::MpsContractor{T}, σ::Vector{Int}, w::S
 ) where {T, S}
     k = get(ctr.node_search_index, w, 0)
     0 < k <= length(σ) ? σ[k] : 1
 end
 
-"""
-$(TYPEDSIGNATURES)
-"""
+
 function boundary_indices(
     ctr::MpsContractor{T},
     nodes::Union{NTuple{2, S}, Tuple{S, NTuple{N, S}}},

diff --git a/src/droplets.jl b/src/droplets.jl
@@ -124,25 +124,24 @@ The `NoDroplets` strategy represents a scenario in which no droplets are present
     spins::Vector{Vector{Int}}
 ) where T = NoDroplets()
 
-"""
-$(TYPEDSIGNATURES)
-
-This method calculates excitation information for the `SingleLayerDroplets` strategy in the context of a SpinGlassPEPS contractor. 
-The `SingleLayerDroplets` strategy represents a scenario in which excitations are calculated for single-layer droplets.
-
-## Arguments 
-- `method::SingleLayerDroplets`: An instance of the `SingleLayerDroplets` strategy.
-- `ctr::MpsContractor{T}`: A SpinGlassPEPS contractor of type `T` representing the system.
-- `best_idx::Int`: The index of the best state.
-- `energies::Vector{<:Real}`: A vector of energies associated with different states.
-- `states::Vector{Vector{Int}}`: A vector of states represented as arrays of integers.
-- `droplets::Vector{Droplets}`: A vector of droplets in the system.
-- `spins::Vector{Vector{Int}}`: A vector of spin configurations associated with states.
+# """
+# $(TYPEDSIGNATURES)
+
+# This method calculates excitation information for the `SingleLayerDroplets` strategy in the context of a SpinGlassPEPS contractor. 
+# The `SingleLayerDroplets` strategy represents a scenario in which excitations are calculated for single-layer droplets.
+
+# ## Arguments 
+# - `method::SingleLayerDroplets`: An instance of the `SingleLayerDroplets` strategy.
+# - `ctr::MpsContractor{T}`: A SpinGlassPEPS contractor of type `T` representing the system.
+# - `best_idx::Int`: The index of the best state.
+# - `energies::Vector{<:Real}`: A vector of energies associated with different states.
+# - `states::Vector{Vector{Int}}`: A vector of states represented as arrays of integers.
+# - `droplets::Vector{Droplets}`: A vector of droplets in the system.
+# - `spins::Vector{Vector{Int}}`: A vector of spin configurations associated with states.
 
-## Returns
-A new `Droplets` object representing the updated droplets based on the `SingleLayerDroplets` strategy.
-
-"""
+# ## Returns
+# A new `Droplets` object representing the updated droplets based on the `SingleLayerDroplets` strategy
+# """
 function (method::SingleLayerDroplets)(
     ctr::MpsContractor{T},
     best_idx::Int,

diff --git a/src/search.jl b/src/search.jl
@@ -9,7 +9,12 @@ export
        decode_to_spin,
        empty_solution,
        branch_energy,
-       no_merge
+       no_merge,
+       sampling,
+       branch_probability,
+       discard_probabilities!,
+       branch_energies,
+       branch_states
 
 """
 $(TYPEDSIGNATURES)

diff --git a/src/square_cross_double_node.jl b/src/square_cross_double_node.jl
@@ -1,4 +1,8 @@
-export SquareCrossDoubleNode
+export 
+    SquareCrossDoubleNode,
+    precompute_conditional,
+    VirtualDoubleNode
+
 
 """
 A geometry type representing a double unit cell square lattice with diagonal next-nearest neighbor interaction.
@@ -216,7 +220,6 @@ The `precompute_conditional` function computes and returns precomputed condition
 It takes into account the geometry of the tensor network, interaction energies, and projectors. 
 The precomputed values are used during the tensor contraction process to speed up the computation.
 The function is specialized for the `SquareCrossDoubleNode` tensor network type and is parametrized by the layout type `S` of the contractor.
-    
 """
 @memoize Dict function precompute_conditional(
     ::Type{T}, ctr::MpsContractor{S}, current_node