Documentation update (#161)

This PR includes a rather large amount of documentation improvements, including but not limited to:

- Documentation infrastructure and structure for docstrings etc
- Documentation infrastructure for worked out examples
- Many docstring improvements
- ...

---------

Co-authored-by: Lukas Devos <ldevos98@gmail.com>
Co-authored-by: Paul Brehmer <paul.brehmer@univie.ac.at>
Co-authored-by: Paul Brehmer <paulbrehmer8@googlemail.com>
Co-authored-by: Yue Zhengyuan <yuezy1997@icloud.com>

Author: 4 people

.github/workflows/DocumentationCleanup.yml

@@ -0,0 +1,33 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+          if [ -d "${preview_dir}" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "documenter@juliadocs.github.io"
+              git rm -rf "${preview_dir}"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+          fi
+        env:
+          preview_dir: previews/PR${{ github.event.number }}

.github/workflows/PR_comment.yml

@@ -0,0 +1,17 @@
+name: Docs preview comment
+on:
+  pull_request:
+    types: [labeled]
+
+permissions:
+  pull-requests: write
+jobs:
+  pr_comment:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create PR comment
+        if: github.event_name == 'pull_request' && github.repository == github.event.pull_request.head.repo.full_name && github.event.label.name == 'documentation'
+        uses: thollander/actions-comment-pull-request@v3
+        with:
+          message: 'After the build completes, the updated documentation will be available [here](https://quantumkithub.github.io/PEPSKit.jl/previews/PR${{ github.event.number }}/)'
+          comment-tag: 'preview-doc'

.gitignore

@@ -2,4 +2,5 @@ docs/build
 Manifest.toml
 examples/.ipynb_checkpoints
 .vscode/
-.DS_Store
+.DS_Store
+**/dev/

Project.toml

@@ -7,6 +7,7 @@ version = "0.5.0"
 Accessors = "7d9f7c33-5ae7-4f3b-8dc6-eff91059b697"
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
 Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 FiniteDifferences = "26cc04aa-876d-5657-8c51-4c34ba976000"
 KrylovKit = "0b1a1467-8014-51b9-945f-bf0ae24f4b77"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
@@ -27,6 +28,7 @@ Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 Accessors = "0.1"
 ChainRulesCore = "1.0"
 Compat = "3.46, 4.2"
+DocStringExtensions = "0.9.3"
 FiniteDifferences = "0.12"
 KrylovKit = "0.9.5"
 LinearAlgebra = "1"

README.md

@@ -30,35 +30,40 @@ The package can be installed through the Julia general registry, via the package
 pkg> add PEPSKit
 ```
 
+## Key features
+
+- Construction and manipulation of infinite projected entangled-pair states (PEPS)
+- Contraction of infinite PEPS using the corner transfer matrix renormalization group (CTMRG) and boundary MPS methods
+- Native support for symmetric tensors through [TensorKit](https://github.com/Jutho/TensorKit.jl), including fermionic tensors
+- PEPS optimization using automatic differentiation (AD) provided through [Zygote](https://fluxml.ai/Zygote.jl/stable/)
+- Imaginary time evolution algorithms
+- Support for PEPS with generic unit cells
+- Support for classical 2D partition functions and projected entangled-pair operators (PEPOs)
+- Extensible system for custom states, operators and algorithms
+
 ## Quickstart
 
 After following the installation process, it should now be possible to load the packages and start simulating.
-For example, in order to obtain the groundstate of the 2D Heisenberg model, we can use the following code:
+For example, in order to obtain the ground state of the 2D Heisenberg model, we can use the following code:
 
 ```julia
-using TensorKit, PEPSKit, KrylovKit, OptimKit
+using TensorKit, PEPSKit
 
 # construct the Hamiltonian
-H = heisenberg_XYZ(InfiniteSquare(); Jx=-1, Jy=1, Jz=-1) # sublattice rotation to obtain single-site unit cell
+H = heisenberg_XYZ(InfiniteSquare())
 
-# choose the bond dimensions
+# configure the parameters
 D = 2
-chi = 20
-
-# configure the algorithm parameters
-boundary_alg = (;
-    alg=:simultaneous, tol=1e-10, verbosity=2, trscheme=(; alg=:truncdim, η=chi)
-)
-optimizer_alg = (; alg=:lbfgs, tol=1e-4, verbosity=3)
-gradient_alg = (; alg=:linsolver)
-reuse_env = true
-
-# and find the ground state
-state = InfinitePEPS(2, D)
-env0, = leading_boundary(CTMRGEnv(state, ComplexSpace(chi)), state; boundary_alg...)
-peps, env, E, = fixedpoint(
-    H, state, env0; boundary_alg, optimizer_alg, gradient_alg, reuse_env
-)
+χ = 20
+ctmrg_tol = 1e-10
+grad_tol = 1e-4
+
+# initialize a PEPS and CTMRG environment
+peps₀ = InfinitePEPS(2, D)
+env₀, = leading_boundary(CTMRGEnv(peps₀, ComplexSpace(χ)), peps₀; tol=ctmrg_tol)
+
+# ground state search
+peps, env, E, = fixedpoint(H, peps₀, env₀; tol=grad_tol, boundary_alg=(; tol=ctmrg_tol))
 
 @show E # -0.6625...
 ```

docs/Project.toml

@@ -1,6 +1,12 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
+KrylovKit = "0b1a1467-8014-51b9-945f-bf0ae24f4b77"
+MPSKit = "bb1c41ca-d63c-52ed-829e-0820dda26502"
+MPSKitModels = "ca635005-6f8c-4cd1-b51d-8491250ef2ab"
 PEPSKit = "52969e89-939e-4361-9b68-9bc7cde4bdeb"
+TensorKit = "07d1fe3e-3e46-537d-9eac-e9e13d0d4cec"
 
 [compat]
-Documenter = "0.27"
+Documenter = "1.0"

docs/make.jl

@@ -1,28 +1,78 @@
+# if docs is not the current active environment, switch to it
+if Base.active_project() != joinpath(@__DIR__, "Project.toml")
+    using Pkg
+    Pkg.activate(@__DIR__)
+    Pkg.develop(PackageSpec(; path=joinpath(@__DIR__, "..")))
+    Pkg.resolve()
+    Pkg.instantiate()
+end
+
 using Documenter
+using DocumenterCitations
+using DocumenterInterLinks
 using PEPSKit
+using MPSKitModels: MPSKitModels # used for docstrings
+
+# bibliography
+bibpath = joinpath(@__DIR__, "src", "assets", "pepskit.bib")
+bib = CitationBibliography(bibpath; style=:authoryear)
+
+# interlinks
+# Zygote didn't update to documenter v1 yet...
+links = InterLinks(
+    "TensorKit" => "https://jutho.github.io/TensorKit.jl/stable/",
+    "KrylovKit" => "https://jutho.github.io/KrylovKit.jl/stable/",
+    "MPSKit" => "https://quantumkithub.github.io/MPSKit.jl/stable/",
+    "MPSKitModels" => "https://quantumkithub.github.io/MPSKitModels.jl/dev/",
+    # "Zygote" => "https://fluxml.ai/Zygote.jl/stable/",
+    "ChainRulesCore" => "https://juliadiff.org/ChainRulesCore.jl/stable/",
+)
+
+# explicitly set math engine
+mathengine = MathJax3(
+    Dict(
+        :loader => Dict("load" => ["[tex]/physics"]),
+        :tex => Dict(
+            "inlineMath" => [["\$", "\$"], ["\\(", "\\)"]],
+            "tags" => "ams",
+            "packages" => ["base", "ams", "autoload", "physics"],
+        ),
+    ),
+)
+
+# examples pages
+examples_optimization =
+    joinpath.(["heisenberg", "bose_hubbard", "xxz", "fermi_hubbard"], Ref("index.md"))
+examples_time_evolution = joinpath.(["heisenberg_su", "hubbard_su"], Ref("index.md"))
+examples_partition_functions =
+    joinpath.(
+        ["2d_ising_partition_function", "3d_ising_partition_function"], Ref("index.md")
+    )
+examples_boundary_mps = joinpath.(["boundary_mps"], Ref("index.md"))
 
 makedocs(;
-    modules=[PEPSKit],
+    modules=[PEPSKit, MPSKitModels],
     sitename="PEPSKit.jl",
     format=Documenter.HTML(;
-        prettyurls=get(ENV, "CI", nothing) == "true",
-        mathengine=MathJax3(
-            Dict(
-                :loader => Dict("load" => ["[tex]/physics"]),
-                :tex => Dict(
-                    "inlineMath" => [["\$", "\$"], ["\\(", "\\)"]],
-                    "tags" => "ams",
-                    "packages" => ["base", "ams", "autoload", "physics"],
-                ),
-            ),
-        ),
+        prettyurls=get(ENV, "CI", nothing) == "true", mathengine, size_threshold=1024000
     ),
     pages=[
         "Home" => "index.md",
-        "Manual" => "man/intro.md",
-        "Examples" => "examples/index.md",
+        "Manual" => ["man/models.md", "man/multithreading.md", "man/precompilation.md"],
+        "Examples" => [
+            "examples/index.md",
+            "Optimization" => joinpath.(Ref("examples"), examples_optimization),
+            "Time Evolution" => joinpath.(Ref("examples"), examples_time_evolution),
+            "Partition Functions" =>
+                joinpath.(Ref("examples"), examples_partition_functions),
+            "Boundary MPS" => joinpath.(Ref("examples"), examples_boundary_mps),
+        ],
         "Library" => "lib/lib.md",
+        "References" => "references.md",
     ],
+    checkdocs=:none,
+    # checkdocs_ignored_modules=[MPSKitModels], # doesn't seem to work...
+    plugins=[bib, links],
 )
 
-deploydocs(; repo="https://github.com/QuantumKitHub/PEPSKit.jl.git")
+deploydocs(; repo="github.com/QuantumKitHub/PEPSKit.jl.git", push_preview=true)

docs/src/assets/pepskit.bib

@@ -0,0 +1,136 @@
+@article{francuz_stable_2025,
+  title = {Stable and Efficient Differentiation of Tensor Network Algorithms},
+  author = {Francuz, Anna and Schuch, Norbert and Vanhecke, Bram},
+  year = {2025},
+  month = mar,
+  journal = {Physical Review Research},
+  volume = {7},
+  number = {1},
+  pages = {013237},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevResearch.7.013237}
+}
+
+@article{evenbly_gauge_2018,
+  title = {Gauge fixing, canonical forms, and optimal truncations in tensor networks with closed loops},
+  author = {Evenbly, Glen},
+  journal = {Phys. Rev. B},
+  volume = {98},
+  issue = {8},
+  pages = {085155},
+  numpages = {11},
+  year = {2018},
+  month = {Aug},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevB.98.085155},
+  url = {https://link.aps.org/doi/10.1103/PhysRevB.98.085155}
+}
+
+@article{sandvik_computational_2011,
+    author = {Sandvik, Anders W.},
+    title = {Computational Studies of Quantum Spin Systems},
+    journal = {AIP Conference Proceedings},
+    volume = {1297},
+    number = {1},
+    pages = {135-338},
+    year = {2010},
+    month = {11},
+    issn = {0094-243X},
+    doi = {10.1063/1.3518900},
+    url = {https://doi.org/10.1063/1.3518900}
+}
+
+@article{vanderstraeten_residual_2018,
+  title = {Residual entropies for three-dimensional frustrated spin systems with tensor networks},
+  author = {Vanderstraeten, Laurens and Vanhecke, Bram and Verstraete, Frank},
+  journal = {Phys. Rev. E},
+  volume = {98},
+  issue = {4},
+  pages = {042145},
+  numpages = {8},
+  year = {2018},
+  month = {Oct},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevE.98.042145},
+  url = {https://link.aps.org/doi/10.1103/PhysRevE.98.042145}
+}
+
+@article{qin_benchmark_2016,
+  title = {Benchmark study of the two-dimensional Hubbard model with auxiliary-field quantum Monte Carlo method},
+  author = {Qin, Mingpu and Shi, Hao and Zhang, Shiwei},
+  journal = {Phys. Rev. B},
+  volume = {94},
+  issue = {8},
+  pages = {085103},
+  numpages = {12},
+  year = {2016},
+  month = {Aug},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevB.94.085103},
+  url = {https://link.aps.org/doi/10.1103/PhysRevB.94.085103}
+}
+
+@article{corboz_variational_2016,
+  title = {Variational optimization with infinite projected entangled-pair states},
+  author = {Corboz, Philippe},
+  journal = {Phys. Rev. B},
+  volume = {94},
+  issue = {3},
+  pages = {035133},
+  numpages = {11},
+  year = {2016},
+  month = {Jul},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevB.94.035133},
+  url = {https://link.aps.org/doi/10.1103/PhysRevB.94.035133}
+}
+
+@article{haegeman_diagonalizing_2017,
+  title = {Diagonalizing {{Transfer Matrices}} and {{Matrix Product Operators}}: {{A Medley}} of {{Exact}} and {{Computational Methods}}},
+  shorttitle = {Diagonalizing {{Transfer Matrices}} and {{Matrix Product Operators}}},
+  author = {Haegeman, Jutho and Verstraete, Frank},
+  year = {2017},
+  journal = {Annual Review of Condensed Matter Physics},
+  volume = {8},
+  number = {1},
+  pages = {355--406},
+  doi = {10.1146/annurev-conmatphys-031016-025507},
+  keywords = {Bethe ansatz,entanglement,equilibrium and nonequilibrium statistical physics,fusion tensor categories,many-body physics,quantum spin chains,tensor networks}
+}
+
+@article{vanderstraeten_tangentspace_2019,
+  title = {Tangent-Space Methods for Uniform Matrix Product States},
+  author = {Vanderstraeten, Laurens and Haegeman, Jutho and Verstraete, Frank},
+  year = {2019},
+  month = jan,
+  journal = {SciPost Physics Lecture Notes},
+  pages = {007},
+  issn = {2590-1990},
+  doi = {10.21468/SciPostPhysLectNotes.7},
+  langid = {english},
+  language = {en}
+}
+
+@article{hasenbusch_monte_2001,
+  author = {Hasenbusch, Martin},
+  title = {Monte Carlo Studies of the Three-Dimensional Ising Model in Equilibrium},
+  journal = {International Journal of Modern Physics C},
+  volume = {12},
+  number = {07},
+  pages = {911-1009},
+  year = {2001},
+  doi = {10.1142/S0129183101002383},
+}
+
+@article{vanderstraeten_variational_2022,
+  title = {Variational Methods for Contracting Projected Entangled-Pair States},
+  author = {Vanderstraeten, Laurens and Burgelman, Lander and Ponsioen, Boris and Van Damme, Maarten and Vanhecke, Bram and Corboz, Philippe and Haegeman, Jutho and Verstraete, Frank},
+  year = {2022},
+  month = may,
+  journal = {Physical Review B},
+  volume = {105},
+  number = {19},
+  pages = {195140},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevB.105.195140}
+}