Docs deploy (#95)

* wip

* Create documentation.yml

* changes to CI

* test for documentation

* test2

* CI modifications

* fixed runs on

.github/workflows/CI.yml

@@ -1,40 +1,58 @@
 name: CI
 on:
-  pull_request:
+  push:
     branches:
       - master
+  pull_request:
   workflow_dispatch:
+env:
+  JULIA_NUM_THREADS: 2
 jobs:
   test:
-    name: Julia ${{ matrix.version }}
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
     runs-on: [self-hosted,titan,gpu]
     strategy:
       fail-fast: false
       matrix:
         version:
-          - '1.11'
+          - 1.11
+        os:
+          - ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
+      - uses: actions/cache@v3
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
       - uses: julia-actions/julia-buildpkg@latest
       - uses: julia-actions/julia-runtest@latest
-        env:
-          JULIA_NUM_THREADS: 4
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: coverallsapp/github-action@master
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          path-to-lcov: lcov.info
-          parallel: true
-          flag-name: run-${{ matrix.version }}
-  finish:
-    needs: test
-    runs-on: [self-hosted,titan]
+      - uses: codecov/codecov-action@v4
+        with: 
+          file: lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false  # or true if you want CI to fail when Codecov fails
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
     steps:
-      - name: Close parallel build
-        uses: coverallsapp/github-action@v1
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
         with:
-          parallel-finished: true
-          carryforward: "run-1.9,run-1.10"
+          version: '1.11'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

.github/workflows/documentation.yml

@@ -0,0 +1,30 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master # update to match your development branch (master, main, dev, trunk, ...)
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: read
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1.11'
+      - uses: julia-actions/cache@v2
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

docs/Project.toml

@@ -7,15 +7,17 @@ MetaGraphs = "626554b9-1ddb-594c-aa3c-2596fe9399a5"
 SpinGlassEngine = "0563570f-ea1b-4080-8a64-041ac6565a4e"
 SpinGlassExhaustive = "a894d7c4-7f54-4100-9d77-d00d924adeb3"
 SpinGlassNetworks = "b7f6bd3e-55dc-4da6-96a9-ef9dbec6ac19"
+SpinGlassPEPS = "2c514f87-1261-494e-8566-326879aaf4fe"
 SpinGlassTensors = "7584fc6a-5a23-4eeb-8277-827aab0146ea"
 
 [compat]
-Documenter = "1.4.0"
-DocumenterTools = "0.1.19"
+Documenter = "1.8.0"
+DocumenterTools = "0.1.20"
 Graphs = "1.9.0"
 LabelledGraphs = "0.4.4"
 MetaGraphs = "0.7.2"
-SpinGlassEngine = "1.0.1"
-SpinGlassNetworks = "1.1.2"
-SpinGlassTensors = "1.1.1"
-julia = "1.9, 1.10"
+SpinGlassEngine = "1.6.0"
+SpinGlassNetworks = "1.4.0"
+SpinGlassTensors = "1.3.0"
+SpinGlassPEPS = "1.5.0"
+julia = "1.11"

docs/src/index.md

@@ -1,6 +1,6 @@
-```@meta
+<!-- ```@meta
 Author = "Tomasz Śmierzchalski, Anna M. Dziubyna, Konrad Jałowiecki, Zakaria Mzaouali, Łukasz Pawela, Bartłomiej Gardas and Marek M. Rams"
-```
+``` -->
 
 # Welcome to SpinGlassPEPS.jl documentation!
 

docs/src/sge/api.md

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

docs/src/sge/search.md

@@ -1,17 +1,14 @@
 # Branch and bound search
-Here you find the main function of the package, which is an actual branch and bound solver.
+Here you find the main function of the package, which is an actual solver.
 
 ```@docs
 low_energy_spectrum
 merge_branches
 merge_branches_blur
 ```
-
-# 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.
+Results of the branch and bound search are stored in a Solution structure.
 ```@docs
 Solution
-SpinGlassNetworks.decode_potts_hamiltonian_state
 ```
 
 # Droplet search
@@ -25,5 +22,4 @@ 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
-```
+```

docs/src/sgn/api.md

@@ -14,12 +14,14 @@ couplings
 ## Potts Hamiltonian
 ```@docs
 split_into_clusters
+decode_potts_hamiltonian_state
 rank_reveal
 energy
 energy_2site
 cluster_size
 bond_energy
 exact_cond_prob
+truncate_potts_hamiltonian
 ```
 
 ## Belief propagation

docs/src/sgn/bp.md

@@ -1,10 +1,7 @@
-## Local dimensional reduction of cluster degrees of freedom
-The `SpinGlassPEPS.jl` package addresses the computational challenges posed by large unit cells, which result in a high number of degrees of freedom per cluster. Contracting tensor networks generated from such Hamiltonians can become numerically expensive. To mitigate this, the package provides an optional local dimensional reduction feature, which reduces the problem's complexity by focusing on the most probable states within each cluster.
-
-This dimensionality reduction is achieved by approximating the marginal probabilities of Potts variables using the Loopy Belief Propagation (LBP) algorithm. LBP iteratively updates messages between clusters and edges to approximate the likelihood of configurations within each cluster. While exact convergence is guaranteed only for tree-like graphs, this method effectively selects a subset of energetically favorable states, even for geometries with loops, such as Pegasus and Zephyr lattices. The details of the Loopy Belief Propagation algorithm are described in [Ref.](https://arxiv.org/abs/2411.16431)
+## Belief propagation
+The `SpinGlassPEPS.jl` package is capable of handling clusters with up to 24 spins, which results in a total of 2^24 degrees of freedom per cluster. This makes the contraction of the tensor network generated from such a Hamiltonian computationally expensive. To address this, `SpinGlassPEPS.jl` offers an optional feature for local dimensional reduction of cluster degrees of freedom by selectively choosing the most probable states within each cluster. This method reduces the dimensionality of the problem by focusing on the most relevant and energetically favorable states. The marginal probabilities of each Potts variable are approximated using the Loopy Belief Propagation (LBP) algorithm.
 
 ```@docs
-truncate_potts_hamiltonian
 potts_hamiltonian_2site
 belief_propagation
 truncate_potts_hamiltonian_2site_BP

docs/src/sgn/clh.md

@@ -1,5 +1,7 @@
 # Introduction
-In `SpinGlassNetworks.jl`, the Potts Hamiltonian serves as a framework for transforming Ising graphs into clustered representations, enabling efficient modeling of complex spin systems. Instead of treating individual spins as separate variables, spins are grouped into clusters corresponding to unit cells of a given lattice geometry. This process reduces the number of variables while increasing their dimensionality, making the system more manageable for tensor-network-based approaches.
+A Potts Hamiltonian is a graphical representation that allows for a convenient and intuitive way to describe the structure of a network.
+
+The concept of a Potts Hamiltonian within `SpinGlassNetworks.jl` introduces a mechanism for organizing spins into desired clustered geometries, facilitating a structured approach to modeling complex spin systems. 
 
 ```@docs
 potts_hamiltonian

docs/src/sgn/lattice.md

@@ -1,11 +1,10 @@
 # Lattice geometries
-The Ising graph serves as the starting point, allowing users to load instances directly from a file and translate them into a graph with vertices numerated using linear indices. To group spins into clusters for the Potts Hamiltonian, it is necessary to map these linear spin coordinates onto the corresponding coordinates of a Potts clusters in a specific lattice geometry. 
-
-The `SpinGlassNetworks.jl` package provides tools for mapping linear indices into three types of lattice geometries, enabling users to adapt the mapping process to the structure of the problem being analyzed. These geometries include super square lattice, Pegasus lattice, and Zephyr lattice, each optimized for specific topologies and applications. For example, in the Pegasus lattice, groups of 24 binary spins are clustered into a single Potts variable, while in the Zephyr lattice, clusters consist of 16 binary spins. 
+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 Potts 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 defines a square lattice with interactions between nearest neighbors (horizontal and vertical connections between unit cells) and next-nearest neighbors (diagonal connections). In `super_square_lattice` function, linear indices of spins from the Ising graph are mapped onto a 2D super square lattice coordinate system (King's lattice). 
-Spins (denoted as black dots in the figure below) are grouped into clusters represented as red ellipses. Every spin in this cluster is indexed coresponding to the square lattice coordinate in the new graph with reduced number of variables of higher dimensions (shown on the right).
+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
 <img src="../images/sd.png" width="200%" class="center"/>
 ```

docs/src/sgn/userguide.md

@@ -1,5 +1,5 @@
 # Introduction
 
-A [Julia](http://julialang.org) package for generating an Ising graphs and clustering binary variables to create effective Potts Hamiltonians. Part of [SpinGlassPEPS](https://github.com/euro-hpc-pl/SpinGlassPEPS.jl) package.
+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 `SpinGlassNetworks.jl` package is illustrated through comprehensive examples, showcasing the practical utilization of key functions. Specifically, the `ising_graph` function is highlighted, demonstrating its capacity to generate Ising graphs from a given instance using a set of standard inputs (e.g., instances compatible with the Ocean environment provided by D-Wave). Additionally, the `potts_hamiltonian` function is presented as a tool for grouping binary variables into clusters with a reduced number of variables of larger dimensions, creating effective Potts Hamiltonians. The package delves into various lattice geometries, providing reindexing of linear Ising coordinates into `super_square_lattice`, `pegasus_lattice`, and `zephyr_lattice`. Moreover, the documentation outlines methods for local dimensional reduction of cluster degrees of freedom.
+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 `potts_hamiltonian` function is presented as a tool for converting Ising graphs into Potts 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.

docs/src/sgt/index.md

@@ -5,9 +5,4 @@ Part of [SpinGlassPEPS](https://github.com/euro-hpc-pl/SpinGlassPEPS.jl) package
 !!! info
     We don't expect the user to interact with this package, as it is more of a "back-end" type. Nevertheless, we provide API references should the need arise.
 
-This section of the package encompasses supplementary functionalities that serve as support for the main solver. `SpinGlassTensors.jl`:
-* includes the creation and manipulation of various types of tensors.
-* offers efficient tools for tensor contractions, in particular it handles tensor contractions in a **sparse** and **dense** mode, enabling efficient memory and computational use depending on the problem's structure.
-* supports QMps (Matrix Product States) and QMpo (Matrix Product Operators) for representing states and operators in a tensor network framework.
-* implements advanced tensor optimization algorithms, including **zipper** algorithm for approximating boundary MPS and **variational** schemes.
-* supports computation on both **CPU** and **GPU**, enabling high-performance tensor operations with the `onGPU` flag in core tensor structures.
+This section of the package encompasses supplementary functionalities that serve as support for the main solver. It includes the creation and manipulation of tensors, with a particular emphasis on implementing Matrix Product States (MPS) and Matrix Product Operators (MPO). 

docs/src/sgt/mpo.md

@@ -1,4 +1,4 @@
-# Matrix Product States and Matrix Product Operators
+# Matrix Product States and Matrix Product Operations
 
 ```@docs
 MpoTensor